Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Solutif Genesys Cloud MCP Server Search for queues named 'support' and show their conversation volumes."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Solutif's MCP server for Genesys Cloud Platform API operations and analytics.
Tool | Description |
Creates a queue after checking for a duplicate name | |
Searches queues by name | |
Retrieves queue conversation volumes | |
Samples conversations from a queue | |
Retrieves voice quality metrics | |
Retrieves conversation sentiment | |
Retrieves conversation topics | |
Searches voice conversations | |
Retrieves a conversation transcript | |
Lists OAuth clients | |
Retrieves OAuth client usage |
Related MCP server: Genesys Cloud MCP Server
npm install
npm run buildConfigure your MCP client to run the local build:
{
"mcpServers": {
"solutif-genesys-cloud": {
"command": "node",
"args": ["/absolute/path/to/genesys-cloud-mcp-server/dist/index.js"],
"env": {
"GENESYSCLOUD_REGION": "<REGION>",
"GENESYSCLOUD_OAUTHCLIENT_ID": "<OAUTH_CLIENT_ID>",
"GENESYSCLOUD_OAUTHCLIENT_SECRET": "<OAUTH_CLIENT_SECRET>"
}
}
}
}The server is read-only by default. To expose create_queue, add:
"GENESYSCLOUD_ENABLE_QUEUE_CREATION": "true"The OAuth client then needs routing:queue:add and routing:queue:view. Keep create_queue out of the MCP client's auto-approved tools so every write requires user approval.
npm run package:mcpbInstall the generated genesys-cloud-mcp-server.mcpb in Claude Desktop. Queue creation is disabled by default and can be enabled in the extension settings.
npm run lint:check
npm run build
npm test -- --runBased on the MIT-licensed MakingChatbots Genesys Cloud MCP Server.
Retrieves sentiment analysis scores for one or more conversations. Sentiment is evaluated based on customer phrases, categorized as positive, neutral, or negative. The result includes both a numeric sentiment score (-100 to 100) and an interpreted sentiment label.
| Name | Required | Description | Default |
|---|---|---|---|
| conversationIds | Yes | A list of up to 100 conversation IDs to retrieve sentiment for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavior: sentiment is evaluated on customer phrases, categorized as positive/neutral/negative, and returns a -100 to 100 score plus a label. However, it does not clarify whether the result is a per-conversation mapping or a single aggregate score when multiple IDs are supplied, and it omits failure or auth context. Annotations contain only a title, so the description carries the transparency burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three focused sentences: the first states the core action, the second explains how sentiment is determined, and the third describes the output. No filler or redundant restating of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-parameter tool with no output schema, the description covers the input and the general nature of the return value. Still, it leaves the output structure ambiguous for batched requests and gives no usage direction relative to nearby analysis tools, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the single conversationIds parameter is fully described with format, minItems, maxItems, and example. The description only restates 'one or more conversations,' adding no meaningful semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Retrieves sentiment analysis scores for one or more conversations.' This clearly distinguishes it from sibling tools like conversation_topics and conversation_transcript, which serve different analysis purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives such as conversation_topics or conversation_transcript. The usage is only implied by the tool's purpose, with no explicit conditions, exclusions, or recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves Speech and Text Analytics topics detected for a specific conversation. Topics represent business-level intents (e.g. cancellation, billing enquiry) inferred from recognised phrases in the customer-agent interaction.
| Name | Required | Description | Default |
|---|---|---|---|
| conversationId | Yes | A UUID for a conversation. (e.g., 00000000-0000-0000-0000-000000000000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description conveys that the operation is a retrieval ('Retrieves') and adds context about how topics are derived ('inferred from recognised phrases in the customer-agent interaction'). With no readOnlyHint or destructiveHint annotations, the description carries the burden, and it partially covers safety and semantics. It does not disclose output shape, empty-result behavior, pagination, or any authentication/data-availability constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no unnecessary wording. The first sentence front-loads the action and object, and the second sentence adds useful semantic context about what topics represent. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple single-parameter retrieval tool, and the description clearly identifies the returned concept (topics) and its meaning. The absence of an output schema is a minor gap because the exact response structure is not described, but for the tool's simplicity the definition is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents the single parameter, conversationId, including its type, format, pattern, and an example. The description adds only the contextual notion of 'a specific conversation', which does not materially expand on the schema. Given 100% schema description coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Retrieves Speech and Text Analytics topics detected for a specific conversation.' It also clarifies what 'topics' mean with examples like cancellation and billing enquiry. However, it does not explicitly differentiate itself from sibling per-conversation tools such as conversation_sentiment or conversation_transcript.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: an agent can infer this tool is appropriate when it has a specific conversationId and needs business-level topics for that conversation. However, there is no explicit when-to-use guidance, no mention of alternatives, and no exclusions to prevent choosing this tool over the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves a structured transcript of the conversation, including speaker labels, utterance timestamps, and sentiment annotations where available. The transcript is formatted as a time-aligned list of utterances attributed to each participant (e.g., customer or agent)
| Name | Required | Description | Default |
|---|---|---|---|
| conversationId | Yes | The UUID of the conversation to retrieve the transcript for (e.g., 00000000-0000-0000-0000-000000000000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no readOnlyHint or destructiveHint in annotations, the description carries the behavioral burden; it explicitly says 'Retrieves', which signals a read operation. It also adds important nuance with 'sentiment annotations where available' and clarifies the time-aligned list format, giving the agent a clear expectation of output behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The first sentence states the core action and payload, and the second sentence adds formatting detail. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter retrieval tool with no output schema, the description covers the invocation requirement and the expected return structure well. It could be slightly more complete by noting behavior when no transcript exists or whether transcripts are paginated, but these are minor gaps given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single parameter, conversationId, including type, format, and an example. The description adds no additional meaning about this parameter, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Retrieves') and resource ('structured transcript of the conversation'), and enumerates the contents: speaker labels, utterance timestamps, and sentiment annotations. It does not explicitly compare itself to sibling tools like conversation_sentiment or conversation_topics, but the transcript focus is distinct enough for an agent to orient.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when a raw, time-aligned conversation transcript is needed. However, it gives no explicit guidance on when to prefer this over sibling tools such as conversation_sentiment, search_voice_conversations, or voice_call_quality, nor does it mention any exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves a list of all OAuth clients, including their associated roles and divisions. This tool is useful for auditing and managing OAuth clients in the Genesys Cloud organization.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description makes the read-only nature apparent through the verb 'Retrieves', and it discloses the scope ('all OAuth clients') and included associations. Since annotations do not provide readOnly/destructive hints, this description carries the burden adequately for a simple list operation, though pagination or rate-limit behavior is not addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, with the core behavior front-loaded and a brief use-case sentence. No unnecessary filler or redundancy; every sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list endpoint, the description covers what the tool does, what data it returns, and typical use cases. It could be slightly more complete by explicitly distinguishing it from oauth_client_usage, but nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema already reflects this fully with 100% coverage. The description appropriately adds context about what the result contains rather than explaining nonexistent parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieves') and a precise resource ('a list of all OAuth clients') with added detail about included roles and divisions. This clearly distinguishes it from sibling tools like oauth_client_usage, which likely focuses on usage metrics rather than client listings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The statement 'useful for auditing and managing OAuth clients' provides a clear context for when this tool should be used. However, it does not explicitly state when not to use it or compare it directly to the sibling oauth_client_usage tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the usage of an OAuth Client for a given period. It returns the total number of requests and a breakdown of Platform API endpoints used by the client.
| Name | Required | Description | Default |
|---|---|---|---|
| endDate | Yes | The end date/time in ISO-8601 format (e.g., '2024-01-07T23:59:59Z') | |
| startDate | Yes | The start date/time in ISO-8601 format (e.g., '2024-01-01T00:00:00Z') | |
| oauthClientId | Yes | The UUID of the OAuth Client to retrieve the usage for (e.g., 00000000-0000-0000-0000-000000000000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no read-only/destructive annotations, but the description clearly indicates a read operation ('Retrieves') and discloses the concrete output: total request count and per-endpoint breakdown. This goes beyond the schema by explaining what the operation returns, though it does not discuss auth requirements or edge cases like empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The purpose is front-loaded and the return behavior is stated immediately, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with three fully documented parameters and no output schema, the description adequately covers what the tool does and what it returns. It could add a bit more about response structure or usage conditions, but nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are fully documented in the input schema. The description only rephrases the time-period concept and does not add new parameter-level semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieves') and a clear resource ('usage of an OAuth Client for a given period'), and it specifies what is returned: total requests and endpoint breakdown. It is clearly distinct from the sibling tool 'oauth_clients' (which likely manages clients), though it does not explicitly name or differentiate itself from that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when OAuth client usage data is needed), but it does not provide explicit when-to-use/when-not-to-use guidance or mention alternatives. The agent must infer usage context from the function description and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a breakdown of how many conversations occurred in each specified queue between two dates. Useful for comparing workload across queues. MAX 300 queue IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| endDate | Yes | The end date/time in ISO-8601 format (e.g., '2024-01-07T23:59:59Z') | |
| queueIds | Yes | List of up to MAX of 300 queue IDs | |
| startDate | Yes | The start date/time in ISO-8601 format (e.g., '2024-01-01T00:00:00Z') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no readOnlyHint or destructiveHint in annotations, the description carries the behavioral burden. It does indicate a read-only reporting action ('Returns a breakdown') and states the MAX 300 queue IDs limit, which is helpful. However, it does not disclose date boundary semantics, how missing/invalid queues are handled, or any other operational behavior beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no wasted words. The core purpose is front-loaded, followed by a practical use case and the key constraint. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no safety annotations, so the description must carry more explanatory weight. It explains what is returned and why to use it, but it does not specify the exact return shape, how dates are interpreted at boundaries, or behavior for invalid queue IDs. Adequate for a simple report tool, but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents queueIds, startDate, and endDate. The description adds only the concepts of 'between two dates' and 'per specified queue,' which reinforces the schema but does not provide significant new parameter-level meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Returns a breakdown'), the resource (queue volumes/conversations), and the scope ('each specified queue between two dates'). This distinguishes it from siblings like sample_conversations_by_queue, which would return sample content rather than volume counts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a use case: 'Useful for comparing workload across queues.' However, it does not explicitly say when not to use this tool or mention alternatives such as sample_conversations_by_queue. Usage context is implied but not fully developed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves conversation analytics for a specific queue between two dates, returning a representative sample of conversation IDs. Useful for reporting, investigation, or summarisation.
| Name | Required | Description | Default |
|---|---|---|---|
| endDate | Yes | The end date/time in ISO-8601 format (e.g., '2024-01-07T23:59:59Z') | |
| queueId | Yes | The UUID of the queue to filter conversations by. (e.g., 00000000-0000-0000-0000-000000000000) | |
| startDate | Yes | The start date/time in ISO-8601 format (e.g., '2024-01-01T00:00:00Z') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only carry a title, so the description carries the full burden of behavioral disclosure. It usefully signals that results are a representative sample of IDs rather than exhaustive data, and 'Retrieves' implies a read operation. It does not mention authentication needs, rate limits, pagination, or the meaning/size of the sample.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The action, scope, and return type are front-loaded, and the use cases are stated compactly in the second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter tool with no output schema, the description covers the purpose, input scope, output type, and likely use cases. It could be more explicit about sample-size behavior or any caveats about the representative sample, but an agent has enough information to select and call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are already documented in the input schema with types, formats, and examples, so schema coverage is 100%. The description only restates the queue-and-date-range relationship and adds no parameter-specific meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Retrieves'), a resource ('conversation analytics for a specific queue'), a date range, and the return type ('a representative sample of conversation IDs'). It does not explicitly contrast itself with siblings like query_queue_volumes or search_voice_conversations, but the sample-of-IDs output is a clear differentiator.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states useful contexts—reporting, investigation, or summarisation—which gives an agent some guidance on when to use it. However, it never mentions alternatives or says when not to use this tool, leaving the choice between this and sibling search tools mostly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches for routing queues based on their name, allowing for wildcard searches. Returns a paginated list of matching queues, including their Name, ID, Description (if available), and Member Count (if available). Also provides pagination details like current page, page size, total results found, and total pages available. Useful for finding specific queue IDs, checking queue configurations, or listing available queues.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name (or partial name) of the routing queue(s) to search for. Wildcards ('*') are supported for pattern matching (e.g., 'Support*', '*Emergency', '*Sales*'). Use '*' alone to retrieve all queues | |
| pageSize | No | The maximum number of queues to return per page. Defaults to 100 if not specified. Used with 'pageNumber' for pagination. The maximum value is 500 | |
| pageNumber | No | The page number of the results to retrieve, starting from 1. Defaults to 1 if not specified. Used with 'pageSize' for navigating large result sets |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide only a title, so the description carries the behavioral transparency burden. It discloses return fields, pagination details, and the wildcard search behavior. For a read-only search tool this is solid, though it doesn't mention edge cases like empty results or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no waste. The description front-loads the core purpose, then gives return content and use cases. Each sentence contributes meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with three scalar parameters and no output schema, the description adequately covers the operation, returned data, pagination behavior, and realistic use cases. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, including wildcard syntax, defaults, and maximum values for pageSize and pageNumber. The description adds minimal new parameter-level meaning beyond the schema—mainly reaffirming wildcard support—so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Searches for routing queues based on their name.' It clearly distinguishes this tool from siblings like search_voice_conversations by focusing on routing queue metadata, and it explicitly states useful applications, so an agent can readily identify what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use cases: 'finding specific queue IDs, checking queue configurations, or listing available queues.' However, it does not explicitly name alternative tools or give when-not-to-use conditions, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches for voice conversations within a specified time window, optionally filtering by phone number. Returns a paginated list of conversation IDs and call duration for use in further analysis or tool calls.
| Name | Required | Description | Default |
|---|---|---|---|
| endDate | Yes | The end date/time in ISO-8601 format (e.g., '2024-01-07T23:59:59Z') | |
| pageSize | No | The maximum number of conversations to return per page. Defaults to 100 if not specified. Used with 'pageNumber' for pagination. The maximum value is 100 | |
| startDate | Yes | The start date/time in ISO-8601 format (e.g., '2024-01-01T00:00:00Z') | |
| pageNumber | No | The page number of the results to retrieve, starting from 1. Defaults to 1 if not specified. Used with 'pageSize' for navigating large result sets | |
| phoneNumber | No | Optional. Filters results to only include conversations involving this phone number (e.g., '+440000000000') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide only a title, so the description carries the behavioral disclosure burden. It states that this is a search returning a paginated list of conversation IDs and call duration, implying read-only metadata retrieval and explicitly excluding transcript content. It does not cover ordering, error behavior, or rate limits, but these are relatively minor for a simple search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences front-load the core action and scoping criteria, then state the output. Every clause contributes useful information with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description adequately specifies the return shape (IDs and duration) and pagination, while the schema fills in parameter details. It could add ordering or empty-result behavior, but nothing essential for selecting and invoking the tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all five parameters with descriptions, examples, and constraints, providing 100% coverage. The description only restates the high-level window, phone filter, and pagination concepts without adding parameter-specific detail beyond the schema, which matches the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Searches') tied to a clear resource ('voice conversations') and adds scoping criteria: a time window and optional phone-number filter. It also states the returned payload (conversation IDs and call duration), which distinguishes it from transcript, sentiment, and topic sibling tools that return content or analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames when to use the tool: finding voice conversations within a date range, optionally filtered by phone number, to obtain metadata for further analysis. It does not, however, name sibling alternatives or state when not to use it, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves voice call quality metrics for one or more conversations by ID. This tool specifically focuses on voice interactions and returns the minimum Mean Opinion Score (MOS) observed in each conversation as structured JSON. MOS is a measure of perceived audio quality based on factors such as jitter, latency, packet loss, and codec. Use the following legend to interpret MOS values:
• Poor: MOS < 3.5 • Acceptable: 3.5 ≤ MOS < 4.3 • Excellent: MOS ≥ 4.3
| Name | Required | Description | Default |
|---|---|---|---|
| conversationIds | Yes | A list of up to 100 conversation IDs to evaluate voice call quality for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no readOnlyHint or destructiveHint annotations, the description carries the burden of behavioral disclosure. It conveys a read-only operation via 'Retrieves,' states the output format as structured JSON, and provides a detailed MOS legend for interpreting results. It does not cover error handling or authentication, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary action, then provides a clear MOS definition and legend. Each sentence earns its place; the legend is slightly long but necessary for interpreting the output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with no output schema, the description covers input, output, and interpretation. It lacks an explicit response shape and behavior for invalid or non-voice conversations, but these are not critical gaps given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents conversationIds thoroughly (UUID format, min/max items), so schema coverage is 100%. The description adds that these IDs are evaluated for voice call quality and that the min MOS is returned, but this is only marginal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Retrieves voice call quality metrics for one or more conversations by ID.' It distinguishes itself from siblings by emphasizing it focuses specifically on voice interactions and returns MOS scores, unlike sentiment or topic tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when you need voice call quality metrics for known conversation IDs. However, it does not explicitly mention alternatives such as search_voice_conversations for finding IDs, nor does it state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0conversation_sentimentconversation_topicsconversation_transcriptoauth_client_usageoauth_clientsquery_queue_volumessample_conversations_by_queuesearch_queuessearch_voice_conversationsvoice_call_qualityScored across 10 tools
Most tools have clearly distinct outputs: transcript, sentiment scores, topics, voice quality, queue volumes, and OAuth usage are separable. A minor overlap exists between conversation_transcript (which can include sentiment annotations) and conversation_sentiment, and between the two conversation-ID discovery tools, but descriptions are enough to resolve this.
The set mixes verb-led names like search_queues and query_queue_volumes with noun-phrase names like conversation_transcript, voice_call_quality, and oauth_clients. The naming is readable and mostly snake_case, but the absent verb pattern prevents strong consistency.
Ten tools is a well-scoped size for a Genesys Cloud server covering conversation analytics, queue interrogation, and OAuth auditing. Each tool has a distinct responsibility and none feel redundant.
Conversation-centric workflows are well covered: discovery, sampling, transcript, sentiment, topics, and call quality are all present. Minor gaps like the lack of non-voice conversation search and OAuth client management actions prevent a perfect score.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Read-only MCP access to sessions, funnels, campaigns, errors, live visitors, and anomalies.
CX ops: read conversations, calls and QA evaluations from Zendesk, Freshdesk, Five9 and more.
Manage AI assistants, history, calls, campaigns, contacts, knowledge, messaging, and automations.
Access Oi Contexts, Workflows, Skills, Guardrails, Connections, and reporting tools.
