Find a Capability by Intent

Start from a phrase like "send a receipt over WhatsApp", end with the name of something you can actually call, and know which of the three searches answers the question you are really asking.

Prerequisites

npm install @codespar/sdk

The REST client used here, cs.api, ships in @codespar/sdk 0.16.0. Nothing has to be connected for path A or path C to answer. Path B needs a project with at least one provider connected, because it ranks provider rails and the connection state feeds the rank.

Three searches, three corpora

The names do not warn you. These are not one search with three transports. They rank different things and they answer different questions.

Pick by the corpus, not by the name. Asking POST /v1/tools/search for a specific provider rail returns a meta-tool, because a provider rail is not in the list it reads. Asking codespar_discover a question about wallet or ledger can return nothing at all, for reasons in the section on reading its result.

Path A: one phrase, one call

The cheapest path. No session, no state, no cleanup.

curl -sS -X POST https://api.codespar.dev/v1/tools/search \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"intent":"charge a customer in BRL with pix","limit":3}'

{
  "intent": "charge a customer in BRL with pix",
  "hits": [
    {
      "tool_name": "codespar_charge",
      "confidence": "high",
      "rationale": "collects money from a customer on a local rail"
    }
  ],
  "elapsed_ms": 412,
  "source": "llm"
}

intent is required and runs 1 to 2000 characters. limit runs 1 to 5, and any larger value is a 400, the copy-paste value 1000 included. tool_name is always one of the 15 published names: the classifier is handed only the name and description of each meta-tool, and anything it invents outside that list is filtered out before the response is built.

There is no named SDK method for this route. In TypeScript it goes through the generic REST client:

import { CodeSpar } from "@codespar/sdk";

const cs = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY! });

const res = await cs.api.post("/v1/tools/search", {
  body: { intent: "charge a customer in BRL with pix", limit: 3 },
});

for (const hit of res.hits) {
  console.log(hit.tool_name, hit.confidence, hit.rationale);
}

From the terminal, the same route is a derived command:

codespar catalog search -i '{"intent":"charge a customer in BRL with pix","limit":3}'

What source tells you, and what it hides

source is llm or fallback, and it is the only decision this route asks you to make.

The handler reads ANTHROPIC_API_KEY from the environment. If it is absent, the model is never called: the response is the lexical heuristic, marked fallback. If it is present, the call goes to claude-haiku-4-5-20251001 with max_tokens 512 and temperature 0. Any throw on that path, a rate limit, a network error, a malformed body, lands in a catch, logs a warning and returns the same heuristic, also marked fallback.

All three outcomes are HTTP 200. This route has no 5xx from the classifier. It is the one point in the contract where a refusal does not arrive as a refusal.

Two more things about the degraded mode, both of which bite agents:

• The heuristic is lexical over English text. It splits the phrase, drops tokens under 3 characters and 22 English stopwords, then counts substring hits in the tool name and description, which are written in English. A Portuguese phrase like "emitir uma nota fiscal de servico" matches nothing and returns an empty list.
• The heuristic never emits high. It emits medium at a score of 2 or more and low below that. A caller that keeps only high throws away 100 percent of the degraded mode.

Empty hits is not a retry signal

The honest branch is to read the catalog instead. It is 15 entries, it needs no credential, it sets Access-Control-Allow-Origin: *, and it is cached for 5 minutes.

if (res.hits.length === 0) {
  const catalog = await fetch("https://api.codespar.dev/meta-tools.json").then((r) => r.json());
  console.log(catalog.generated_from); // "tools/list"
  for (const tool of catalog.tools) {
    console.log(tool.name, tool.description);
  }
}

GET /v1/meta-tools.json returns the same bytes, for clients already pointed at the versioned prefix. Offline, codespar tools meta prints the published definitions straight out of @codespar/types without touching the network.

Path B: search the raw provider catalog

codespar_discover ranks mcp_tools, which is the table of provider rails. It is reachable only inside a session, so a read question costs four HTTP calls.

import { CodeSpar } from "@codespar/sdk";

const cs = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY! });

// 1. A real server id. GET /v1/servers is the deprecated alias of this route.
const catalog = await cs.api.get("/v1/providers");
console.log(catalog);

// 2. servers has minItems 1 and maxItems 20. An empty array is a 400.
const session = await cs.create("user_123", { servers: ["asaas"] });

try {
  // 3. Sugar over session.execute("codespar_discover", { use_case, ... }).
  const result = await session.discover("send a whatsapp message to a customer", {
    limit: 5,
    country: "BR",
  });

  console.log(result.search_strategy);
  console.log(result.recommended);
  console.log(result.related);
  console.log(result.next_steps);

  // meta_tools is returned at runtime and absent from the published type.
  const native = (result as unknown as { meta_tools?: unknown[] }).meta_tools;
  console.log(native);
} finally {
  // 4. Idempotent. Closing a closed session returns the original closed_at.
  await session.close();
}

The raw call underneath, if you want the untouched envelope:

curl -sS -X POST https://api.codespar.dev/v1/sessions/$SESSION_ID/execute \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"codespar_discover","input":{"use_case":"send a whatsapp message","limit":5}}'

The order things happen in

The route validates before it does anything else, and the checks are ordered. Knowing the order tells you what already happened when an error arrives.

1. The body is parsed. A failure is 400 invalid_body.
2. The session status is checked. A closed session is 409 session_not_active.
3. The org quota is checked. Over the line is 403 quota_exceeded.
4. The tool is resolved: codespar_list_tools first, then the meta-tool table, then the registered catalog. Nothing matching is HTTP 200 with success: false and Tool not registered.
5. Arguments are coerced, then the per-action scope gate runs. codespar_discover maps to tools:execute, and the gate only refuses when the deployment sets META_TOOL_ACTION_SCOPES_ENFORCE=true, which is off by default.

Inside the tool, use_case is read first, with query accepted as a compatibility alias. If both are missing or empty, it throws invalid_args before it touches the database. Nothing is written, nothing is charged, and the HTTP status is still 200.

codespar_discover is also diverted before the tool router. No eligibility check, no failover, no telemetry, no idempotency_key. It is a pure read.

How it actually searches

The semantic pass asks OpenAI for an embedding of the query, with a 5 second abort. It returns nothing when OPENAI_API_KEY is unset, when the response is not ok, and on any exception or timeout. With a vector, the query selects over mcp_tools rows that have an embedding and orders by cosine distance. Zero rows there, or no vector at all, and it falls to trigram similarity at threshold 0.1 over tool_name and description, plus the provider's own name and description weighted at 0.7. That weighted pair is why "send whatsapp message" finds the z-api rails. Zero rows in both passes sets search_strategy to empty.

Ranking adds a connection bonus, 0.02 on the cosine path and 0.05 on the trigram path, for rails that are connected or need no connection. In environment=test a disconnected rail behind non self-serve auth, a certificate, an HMAC pair, a JWT or a two-header scheme, takes a penalty of 1000, which buries it.

Reading the discover result without falling in

Four more traps in this response.

• meta_tools is not in the published type. The served description of the tool says to prefer a native meta-tool when one is returned, and the backend returns them under meta_tools. DiscoverResult in @codespar/types 0.11.0 declares use_case, search_strategy, recommended, related and next_steps, and nothing else. TypeScript callers need a cast to see the field. The information survives in typed code only through the text of next_steps[0].
• meta_tools knows 10 of the 15. The hint table covers shop, manage_connections, pay, charge, invoice, ship, notify, kyc, crypto_pay and checkout. codespar_discover is excluded deliberately, since a tool never recommends itself. wallet, ledger, issue and get_started are absent with no note. An intent about balances, statements, the ledger or card issuing never surfaces through this field, and when the mcp_tools catalog also fails to match, the answer is empty for a capability that exists.
• What it recommends is often not callable from where you asked. recommended and related are catalog rows, shaped as server_id.tool_name. The hosted agent transport accepts only the 15 published meta-tool names plus codespar_list_tools, so an answer like asaas.create_transfer names a tool that transport refuses. Raw catalog tools run only through POST /v1/sessions/{id}/execute.
• This search sees your tenant. Path A does not. POST /v1/tools/search never reads the auth context: no org, no project, no environment, no connection state. Its answer is byte identical for every caller. codespar_discover checks connected accounts per org and project, adds the connection bonus, and hides generated tools belonging to another project. Treating them as the same search with a different transport leads to recommending a rail the tenant cannot invoke.

Path C: pick the provider, not the tool

POST /v1/meta-tools/discover is not a tool search. It takes an operation you have already chosen and picks the rail that will carry it.

curl -sS -X POST https://api.codespar.dev/v1/meta-tools/discover \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"intent":{"operation":"charge","currency":"BRL","country":"BR","amount_minor":4990}}'

operation is one of charge, refund, payout, issue_invoice, send_notification and ship. With currency and country it is required. amount_minor, urgency, recipient_kind and metadata are optional. In that structured form the lookup is deterministic and free.

The alternative body is { "description": "..." }, 1 to 2000 characters, which needs the managed-tier extractor. Without it the answer is 501. There is no named SDK method for this route in TypeScript or Python, and no CLI command. The generic REST client reaches it as cs.api.post("/v1/meta-tools/discover", { body }).

Order inside: the intent is resolved, structured or extracted, then mapped to a meta-tool and a rail, then routed over org, meta-tool, rail, currency and country. An intent that maps to nothing is 400 intent_unmappable, and operation: "ship" lands there every time.

Two fields on the response invite misreading. provider_id is transparency, not a reservation: the router runs again at execution time and may pick a different rail, which the served description says outright. An empty alternatives array is not a failure, it means exactly one route was eligible. And args_template never carries action, which every money meta-tool requires. It fills currency, metadata, and amount only for codespar_pay, so for any other meta-tool the amount_minor you sent is dropped in silence.

Refusals, and which retry fixes which

One SDK detail that flattens this table into a single shape: session.execute does not throw on a non-2xx. It synthesizes success: false with error set to the status and the body joined into one string. A policy 403 and an unregistered tool arrive in the same object, and only the prefix of that string separates them. session.discover throws on top of that, with the message discover failed: and the error text.

What this does not do

• It does not run path C from the CLI. The meta-tools group is excluded from the derived command surface, with the stated reason that codespar discover already calls it. That reason is wrong: codespar discover calls session.discover, which executes the codespar_discover meta-tool inside a session. The two surfaces share a word and nothing else. From the terminal, path C is curl only.
• It does not give path A a named SDK method. TypeScript reaches it through cs.api.post and the generated operations table. The Python package has no reference to the route at all.
• It does not give path C a named SDK method either. session.discover() is not a wrapper for it.
• It does not declare meta_tools on DiscoverResult. The runtime returns the field, @codespar/types 0.11.0 does not declare it.
• It does not publish the agent transport in the OpenAPI document. None of the 276 paths in the served document ends in /mcp. The routes exist and the scope map knows them, but a client working only from the specification cannot learn that the transport exists.
• It does not expose codespar_discover over a single call. There is no HTTP route that returns its result without opening a session. The one-call route, POST /v1/tools/search, answers over a different corpus.
• It does not confirm that a provider exists. GET /v1/servers/{id}/tools answers 200 with an empty list for an id that names no provider. The response cannot tell a real provider with no tools from one that was never there.
• It does not reach codespar_cart. The tool has a dispatch branch and a scope mapping, and no entry in the published catalog, so the live meta-tools.json lists 15 names without it. Executing it returns 200 with Tool not registered, and none of the three searches can return it.
• It does not work from codespar discover against the live API. In @codespar/cli 0.11.2, both codespar discover and codespar tool <name> open the session with an empty servers array. The SDK passes that through, and POST /v1/sessions refuses it with 400 invalid_body, which the CLI surfaces as an internal error with a stack trace and exit code 2. Use codespar catalog search for path A, or the SDK for path B.