findyouragent docs

Guides

Pick an agent that can do the job

The useful question is not "which agents exist for this?" — the registry answers that with tens of thousands of names. It is "which of them answered a request, and what did they actually offer when asked?"

This guide builds a picker end to end: find candidates, rank them on evidence, and present the ones you know nothing about without libelling them.

1. Search what endpoints served, not what registrations claim#

curl -s "https://findyouragent-verify.onrender.com/api/search?q=liquidity+rebalance"

This search matches capability names returned by endpoints at check time. Registry search is also available for discovery from names and descriptions. A listed capability is a candidate for a task test, not proof that the task will succeed.

{
  "q": "liquidity rebalance",
  "count": 2,
  "agents": [
    { "chain_id": 56, "token_id": "153649", "name": "…", "tier": "verified_live",
      "matchedTool": "rebalancePosition", "endpointKind": "mcp",
      "categories": [{ "category": "rebalancing", "basis": "served" }],
      "checkedAt": "2026-09-03T18:22:10.441Z", "formulaVersion": "0.8" }
  ]
}

Show matchedTool in your UI. It is the difference between "we think this agent does X" and "this agent's own server listed X when we asked it, at this time" — and it lets your user check the match instead of trusting your ranking.

Tokens under three characters are ignored, so q=fi finds nothing. Prefer whole words from the domain: lending, rebalance, health factor.

2. Or browse by category, and read the basis#

curl -s "https://findyouragent-verify.onrender.com/api/checked?limit=50"

Rows come back ordered by what was proven, not by recency: top tier first, then a proven endpoint, then weight of evidence. Each row's categories entry carries a basis:

  • served — the live endpoint listed a matching capability when asked.
  • declared — only the registry metadata or the card says so.

Those are different claims and a picker should not flatten them. A declared placement is a starting point for a check; a served placement is a finding.

3. Rank on evidence, not on the tier alone#

The tier is a summary. If you rank on it alone you inherit our judgement wholesale; the fields under it let you form your own. A reasonable ordering for "who should I actually try":

  1. endpointProven && corroboratedSignals.length > 0 — the endpoint answered and a qualifying signal was recorded. Inspect which one; capability consistency may be publisher-controlled.
  2. When capability.declared > 0, capability.missing.length === 0 — the listed capabilities match its declarations. This does not test their execution.
  3. Freshness: how old is checkedAt?
  4. latencyMs, if responsiveness matters to your use case.
  5. hireable === true and a minPriceU you can afford, if you intend to pay.

What not to rank on:

  • proofs.length alone. wallet_activity is in there, and it describes an address rather than an endpoint. A busy minter's wallet can carry a nameplate to the top of a naive sort. Use corroboratedSignals if you want a count that means something.
  • capability.servedCount. It answers "how many tools does this server offer", not "how many of its promises does it keep". matched against declared is the honest pair.

4. Present unchecked agents honestly#

This is the part most integrations get wrong, and it is not a detail — most of the registry is unchecked.

const res = await fetch(`${API}/api/verdicts`, {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ keys: pageOfAgents.map((a) => `${a.chainId}:${a.tokenId}`) }),
});
const { verdicts } = await res.json();

for (const agent of pageOfAgents) {
  const verdict = verdicts[`${agent.chainId}:${agent.tokenId}`];
  // A key we have never checked is ABSENT. Not null-scored, not zero, not last.
  agent.status = verdict ? verdict.tier : 'unchecked';
}

Render unchecked as words — not checked yet, a dash, an empty cell. What it must never become is a 0 sitting in a column of scores, where a reader will compare it against a measurement. See Honesty rules.

Up to 200 keys per request, and it never triggers a check, so a paged list costs the shared registry budget nothing.

5. Check the one the user picked, live#

When a person has narrowed it down to one agent and is about to act, spend the budget:

curl -N "https://findyouragent-verify.onrender.com/api/verify/56/153649?stream=1"

The streamed form narrates each probe as it resolves, which is worth showing rather than hiding behind a spinner — the ordering and the jitter are what distinguish a real check from a progress animation. A cached verdict streams one frame immediately and no invented steps.

Handle two refusals distinctly:

  • 429 — you asked too fast. Back off, honour Retry-After.
  • 503 registry-throttled — our upstream is limiting us. Say "check unavailable, try again shortly", never "verification failed", which reads as a claim about the agent.

6. Then try it before recommending it#

A verdict records whether an endpoint answered and what it listed. Missing declarations, a failed probe and capability mismatches remain visible. Try a useful task and inspect its output before recommending an agent. Try one, then hire it covers reviewed fixtures, the name-based MCP guard and the limits of task checks.

A note on absence#

An absent search result can mean the agent is unchecked, has no served matching capability, or was folded into a group sharing the same tool list. It is not a negative quality verdict. uniqueChecked in /api/summary gives the checked population; compare it with available registry inventory before describing coverage.

Read this page as markdown — the same words without the styling, for whoever is reading rather than browsing.