Onepin

Find voices

find_voices

Read-only

Search for voice candidates — the ONLY tool that may search or recommend voices.

Call before preview_voice unless the user named a valid catalog_voice_id. Returns at most three, vetted but not ranked, with no audio: preview_voice each to compare, then let them say which is theirs. Never pick a voice for the user.

Input Schema

Name	Required	Description
`age`	No	A hard filter, not a preference. Set it only when the user did.
`limit`	No	How many candidates to return. Preview each one.
`model`	No	One TTS model, named as list_providers names it.
`style`	No	How it should SOUND — "warm low male narrator". Ask the user, put their answer here.
`accent`	No	A hard filter, and setting it turns recommendation off. Prefer style.
`cursor`	No	Pass next_page from a previous result to get DIFFERENT voices. Never invent one.
`gender`	No	A hard filter, not a preference. Set it only when the user did.
`search`	No	Find a voice by NAME. Use style for how it should sound.
`category`	No	A hard filter, and setting it turns recommendation off. Prefer style.
`language`	No	The language it must speak — a family (`ko`) or a locale (`ko-kr`).
`provider_voice_id`	No	Exact vendor voice id (e.g. an ElevenLabs id). Not a name — use search for that.

Output Schema

Name	Required	Description	Default
`voices`	No
`next_page`	No
`next_step`	No
`matched_by`	No
`total_matching`	No
`total_matching_capped`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 23, 2026
- addedOutput schema / $defs / VoiceRow / properties / naturalness
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```
First observedOct 14, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only cover readOnly/openWorld; the description adds the substantive behavior: a hard cap of three results, results are "vetted but not ranked," and no audio is returned. It also discloses the intended human-in-the-loop contract, which is exactly the kind of trait annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences with the exclusivity claim and the call-order rule front-loaded. No filler, no restatement of the title, and the closing imperative lands last where it is most actionable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter, all-optional search tool with an output schema and full schema coverage, the description supplies everything the schema cannot: result count, ranking posture, absent audio, and the preview handoff. Return-value details are correctly left to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and each parameter's own description already carries the hard-filter-vs-style distinction and the cursor rule, so the description adds little parameter-level meaning. Its only implicit parameter reference ("a valid catalog_voice_id") does not map cleanly onto any schema field, which is mildly confusing but not harmful. Baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Search for voice candidates") and immediately stakes exclusivity: "the ONLY tool that may search or recommend voices." An agent can separate this from list_providers, preview_voice and set_workflow_voice without reading any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit ordering rule ("Call before preview_voice unless the user named a valid catalog_voice_id") and an explicit constraint ("Never pick a voice for the user"), plus the downstream step (preview_voice each to compare). When-to-use, when-to-skip, and the alternative are all named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Onepin tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?