codespar_discover

Find the right tool for a free-form use case. Returns the recommended catalog tool with its connection status, pitfalls, plan and related tools, plus any native meta-tool that covers the same job.

Shared railUsed by buy-side and sell-side agents alike; not tied to a money direction.

Semantic search across the catalog.

tool codespar_discoverone operationmoves no moneyalways required use_case

Use it when you do not already know the canonical tool name to call. When a native meta-tool comes back in meta_tools, prefer it.

Actions

Operation	What it does	Money	Needs
single call, no selector	Find the right tool for a free-form use case; native meta-tools that cover the job come back in meta_tools	no	—

Names come from the published tool document (/v1/meta-tools.json, the same list the MCP server answers to tools/list); the one-line summaries and the money class are kept in the docs repository and checked against it on every build.

Example

Call · tools/call

arguments

{
  "name": "codespar_discover",
  "arguments": {
    "use_case": "send a Pix to a supplier",
    "country": "BR",
    "limit": 5
  }
}

Result · fields the tool document names

result

{
  "meta_tools": ["codespar_pay"]
}

Alongside meta_tools, the tool document says the result carries the recommended catalog tool, its connection status, known pitfalls, a recommended plan and related tools; it does not name those fields. Full shape: see runtime, via /v1/meta-tools.json.

When to use

An open intent ("buy a TV", "save my address", "send a Pix") before you know which tool does it. buy a TV surfaces codespar_shop, send a Pix surfaces codespar_pay, save my address surfaces codespar_manage_connections.
Once per intent, then cache the answer for the conversation: the call queries the live catalog and the embedding index and counts as a tool call.
Paired with codespar_manage_connections when the best match is not connected: discover finds the tool, manage_connections tells you whether this user can reach it and hands back the connect flow if not.
Not for setup questions. "How do I start / what can you do" is codespar_get_started, which returns the ordered happy path for the workspace without a discovery detour.

Arguments

Field	Type	Required	Description
`use_case`	`string`	Yes	Free-form description of what you want to accomplish ("send an email", "create a Pix payment"). Describe the intent, not the tool name
`category`	`string`	No	Optional category filter
`country`	`string`	No	ISO 3166-1 alpha-2, or `*` for any
`limit`	`number`	No	Max related tools returned, 1..20, default 5

Errors and what to do

Error	Cause	What to do
`invalid_args`	`use_case` missing.	Pass a sentence describing the intent.
A best match that is not connected	The ranked results are biased toward providers the session has already connected, but the top match can still be unconnected.	Check it with `codespar_manage_connections` `status`, and surface the connect flow from `initiate`.

Money and mandate

Nothing moves. The call reads the catalog index in the CodeSpar backend; no provider is called and no mandate is involved. The tools it recommends have their own gates.

codespar_get_started: the happy path when the question is about setup
codespar_manage_connections: check and unblock the recommended tool
SDK reference, discover: the typed wrapper
Tool router: how the catalog is scored at execute time

Notes

Two-stage retrieval, as previously documented. Semantic first (the query is embedded with OpenAI text-embedding-3-small, 1536 dimensions, and cosine-ranked against mcp_tools.embedding), then a pg_trgm lexical fallback over tool_name + description when the semantic pass returns thin results. Ranking is biased toward connected providers: a connected match outranks a higher-scoring unconnected match at the margin, on purpose. Operators populate the embedding column with the embed-mcp-tools.ts seed script, which is idempotent (it re-embeds only rows whose description_hash changed); the managed-tier runbook covers re-embedding when the catalog changes. No tenant stamps an OpenAI key for this; the embeddings call is on CodeSpar's side.

Result shape (SDK), as previously documented. session.discover(query) returned { matches: Array<{ tool_name, server_id, score, description, connected }> }. That wrapper takes a query string; the MCP tool takes use_case. This revision did not re-verify the list against the runtime, and the MCP result is not documented to have the same shape (the tool document names meta_tools).

From the SDK. session.discover("emit a Pix QR code for a buyer in Brazil") in TypeScript, session.discover(...) in Python; or session.execute("codespar_discover", arguments) with the same arguments as the MCP call.

codespar_discover

On this page