What we learned shipping 73 public-data endpoints as MCP tools — tool naming, descriptions, parameter schemas, and how Claude picks the right one.

UnifAPI exposes every endpoint in the catalog — currently 73 across 14 social platforms — as an MCP tool. Doing that well is harder than it looks: the model sees the tool list as a prompt, and a sloppy tool surface degrades reasoning quality more than people expect. This is what we learned about naming, descriptions, parameter schemas, and the failure modes that don't show up until you have dozens of tools live.

Why 73 tools is a lot

At 5-10 tools, MCP "just works" — the model reads the list, picks one, calls it. At 20-30, naming starts to matter; you see the model occasionally pick the close-but-wrong tool. At 50+, the tool list itself starts eating context budget and the description quality of each tool becomes load-bearing.

We're at 73. That count keeps growing as we add platforms (search, scrape, and news are on the roadmap, each adding 5-15 endpoints). The discipline that gets you from 5 to 73 without quality regression is the focus of this post.

Tool naming: agent-readable, not human-readable

Our tool names follow one pattern: <platform>_<verb>_<noun>. tiktok_search_videos, reddit_get_post, linkedin_search_people. Verbose, but unambiguous. The model picks the right one because the name reads like a sentence fragment, not a code identifier.

We tried shorter conventions early — tiktok.search, reddit.post — and saw the model pick wrong on close pairs ("search" on TikTok vs. "search" on Reddit when the user said "search"). The platform prefix in the name disambiguates without the model having to reason about it.

Descriptions are the prompt

Each tool's description is one or two sentences. The model has to read them all every call. Two patterns that earn their tokens: lead with the verb-object summary in the first 12 words, and end with a use-when hint.

Good: "Search TikTok for videos matching a keyword or hashtag. Use when the user wants short-video discovery on a topic." Bad: "This endpoint allows you to query the TikTok platform and retrieve a paginated list of videos that match a search term, optionally filtered by various parameters including ..." The second one is technically more complete and is the wrong tradeoff at 73 tools.

Parameter schemas: keep them flat

Every tool we ship takes a flat object: top-level fields, no nesting more than one level deep, no oneOf / anyOf branches. Required fields first, optionals after. The reason is simple: nested JSON schemas confuse the model's tool-call generator. We've watched Claude correctly understand a parameter and then output it at the wrong nesting level because the schema looked branchy.

When an endpoint genuinely needs polymorphic input (search by keyword OR by hashtag), we expose two tools, not one tool with a discriminated union. Two tools the model can pick between beats one tool with branchy parameters every time.

What we got wrong

Three mistakes worth naming. First, we let Twitter and Reddit have nearly-identical descriptions for their respective search tools, and the model started picking one when the user explicitly asked for the other. Fixed by making each description name its platform explicitly in the first sentence.

Second, we returned upstream error messages straight through for a while. Some of those reference platform-specific concepts the model doesn't understand, and the agent would loop trying to fix an issue our envelope was hiding. Fixed by normalizing errors into a four-category set: rate_limited, not_found, upstream_unavailable, bad_request.

Third, we under-documented pagination on a few endpoints, and the model would re-call from cursor 0 every loop instead of advancing. Fixed by spelling out the pagination contract in the tool description itself, not just in the spec.

Open questions

At what point do we partition the tool list? 73 fits in one MCP server today, but if we hit 200 with the roadmap shipping, the tool list will probably need namespacing — separate MCP servers per category (social.unifapi.com, search.unifapi.com) so the model only loads the tools it needs.

We don't know the right answer yet. If you're shipping agents that consume a lot of UnifAPI tools today, we want to hear how the tool-pick latency looks on your end — drop us a note at hello@unifapi.com.