Skip to main content
Glama

Search Specs

search_specs
Read-onlyIdempotent

Searches specs by words and filters by category, channel, provider, country, currency, status or capability type. Returns the matching providers, each with its countries, currencies, sandbox flag, docs URL and the matching capabilities (name, type, status, example_prompt) — no endpoints, schemas, gotchas or canonical_example source. Use get_spec with the exact capability name to retrieve the full payload. A capability with "variants" has several request/response shapes (e.g. one per payment method or corridor): pass the ones you need to get_spec "variant" to receive only those.

Each result includes a "status" field:

  • "verified": tested against the provider's API, in "sandbox" or "production" (verified_in / verification.environment)

  • "deprecated": the provider is retiring it — get_spec says what replaces it

  • anything else (e.g. "ready", "unverified"): written from the provider's documentation, NOT tested against the live API — may contain errors

Always check the status field. If status is not "verified", inform the user that the spec is experimental and may contain errors.

Args:

  • query (string?): Words, e.g. "wave", "mobile money senegal", "send sms", "kyc", "XOF". Every word must match somewhere: provider name or slug, capability, description, example_prompt, countries (code or English/French name), currencies, channels (a few synonyms: momo, otp, kyc, payout…). Providers the query names come first.

  • category (string?): Filter by category, e.g. "payment", "communications" (SMS, WhatsApp, USSD, voice and email providers — "sms" is accepted as a legacy alias), "identity" (KYC, document verification, AML), "logistics" (delivery and courier providers). The registry adds categories over time: list_providers shows every category that exists

  • channel ("sms"|"whatsapp"|"ussd"|"voice"|"email"?): Only providers that offer this channel

  • provider (string?): Provider slug e.g. "paycard"

  • country_code (string?): ISO 3166-1 alpha-2 e.g. "GN"

  • currency (string?): ISO 4217 e.g. "XOF"

  • status ("verified"|"ready"|"unverified"?): e.g. "verified" for specs tested against the provider's API

  • capability_type ("synchronous"|"asynchronous"|"webhook"|"sdk"?): Filter by capability type

Returns: { providers: ProviderMatch[], note?: string, hint?: string, unverified_count: number, warning?: string } Each provider may carry "account": who can open its account, with its open questions (see list_providers, which also has the sources). note is present when a wide result was trimmed to stay readable: example_prompt first, then variants, then the whole account (never an account's answers without its open questions) — it says which; call list_providers for the accounts, get_spec for the variants. hint is present when nothing matched: widen the search before telling the user a provider is unavailable. unverified_count counts matching capabilities whose status is not "verified"; warning is present only when it is > 0.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_specs"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryNoWords, e.g. "mobile money senegal" — every word must match
statusNo
channelNo
categoryNo
currencyNoISO 4217 e.g. "XOF"
providerNoProvider slug e.g. "paycard"
country_codeNoISO 3166-1 alpha-2 e.g. "GN"
capability_typeNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already declare read-only, idempotent, non-destructive, closed-world, so the safety profile is covered; the description goes further by disclosing what the results deliberately omit (endpoints, schemas, gotchas, canonical_example source) and the trimming behavior when a result is wide. The status taxonomy (verified/deprecated/other) and the meaning of unverified_count and warning are genuine behavioral context. Minor gap: it doesn't say whether results are paginated or capped beyond the trim note, but overall this is well above the annotation baseline.

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

Conciseness4/5

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

Front-loaded with purpose, then returns, then usage rules, then a sectioned args/returns block, which is a sound structure for a complex tool. It is verbose, though: the second paragraph already lists what each provider carries (countries, currencies, sandbox flag, docs URL, capabilities), and the "Returns:" block repeats that field inventory, and several Args entries restate the schema examples nearly verbatim.

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 eight-parameter, no-output-schema search tool, the description covers the return shape, the per-provider fields, the optional "account" object, note/hint/unverified_count/warning semantics, and the variant follow-up path. An agent could call this correctly and interpret every field without further context.

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

Parameters5/5

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

Schema coverage is only 50% and the schema leaves status, channel, category and capability_type entirely undescribed — the description compensates fully. It explains the query matching rule ("Every word must match somewhere", listing the matched surfaces and synonyms), gives concrete category values with the "sms" legacy alias, notes categories grow over time via list_providers, and defines what "verified" means as a filter value.

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?

Opens with a specific verb-plus-resource plus the full filter set: "Searches specs by words and filters by category, channel, provider, country, currency, status or capability type." It also distinguishes itself from siblings by naming the exact handoff ("Use get_spec with the exact capability name to retrieve the full payload") so an agent can separate search from fetch without reading either 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?

Explicitly routes the agent: search here for discovery, get_spec for full payload, get_spec "variant" for specific shapes, list_providers for categories/accounts, and widen the search when a hint is returned. It adds a decision rule for the results themselves — "Always check the status field. If status is not verified, inform the user that the spec is experimental" — which is a usage instruction, not just a description.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.