Discover Resources

Discovery begins with a need. You describe the task, optionally add resource type, protocol, and capability filters, then inspect the candidates returned by a Discovery node. The best mental model is simple: Discovery helps you find candidates; verification decides whether a candidate should be used.

The official Discover page is intentionally lightweight. It should be easy to type a natural-language query, add capability tags as chips, choose a resource type if needed, and review results. More complex explanation belongs in Docs and SDK tooling.

For most users, Discovery should feel like asking for help rather than filling out a database query. The underlying system may use filters, vector search, lexical matching, ranking, and proof verification, but the user-facing entry can remain a task description plus a few useful constraints.

Write a Useful Query

Good queries describe tasks and constraints, not only single keywords. For example:

If you know the resource type, use the type filter. If you know the protocol you want, use the protocol filter. If you know capability tags, add them. But do not over-filter early; a semantic Discovery engine can often find relevant candidates from a well-written query.

Queries should describe the desired outcome. “Review OpenAPI security risks” is better than “security” because it tells Discovery the resource should understand API descriptions and risk analysis. “Search a knowledge base through MCP” is better than “docs” because it includes the protocol expectation.

Read Candidate Results

A Discovery result should be read as a resource candidate with evidence. Useful result cards should include:

• resource name and summary;
• resource type;
• DID or resource identifier;
• capability tags;
• authorized domains;
• lifecycle or status;
• package or Root proof references;
• endpoint, manifest, schema, or artifact references;
• reason, score, or explanation when available.

Do not treat the top result as automatically safe. Ranking answers relevance, not trust by itself.

The strongest result card is one that explains both why the candidate matched and what evidence supports it. Relevance may come from descriptions, examples, tags, or semantic similarity. Trust comes from DID identity, Root proof, lifecycle, hashes, and node authorization. These two ideas should be visible as different parts of the result.

Verify Before Use

Before installing or invoking a result, check the OAN evidence. The client or SDK should verify Discovery response signature, Root proof, package hashes, DID Document hash, lifecycle state, and endpoint or artifact binding. If you are using the website manually, inspect the trust details and follow links to package or source material where available.

After OAN verification succeeds, apply the native protocol’s own checks. MCP connection setup, API authentication, skill installation policy, endpoint authorization, and enterprise approval are still relevant.

If you are using an SDK, prefer SDK methods that return verified candidates rather than raw HTTP responses. If you are using the website, treat links and proof fields as part of the result rather than decorative metadata. If you are building an agent, make verification a required step before the agent can install or call a discovered resource.

Use Tags and Filters Correctly

Capability tags help express what you need: summarization, contract-review, mcp-server, code-analysis, workflow-automation, and similar terms. Tags are matching hints. They do not grant domain authorization.

Resource type filters are stronger structural filters. If you need a Skill package, selecting skill avoids hosted Agent Services and APIs. If you need an MCP endpoint, selecting mcp_server avoids ordinary HTTP APIs. Protocol filters can further narrow integration expectations.

Authorized-domain filters should be used when domain scope matters. They are not just topical keywords; they relate to publication and Discovery scope.

In many cases, a user does not need to set a domain filter manually. The Discovery node’s own authorization already limits what it can expose. Domain filters are most useful when the user wants to narrow a broad search, compare behavior across nodes, or test whether domain-scoped visibility works as expected.

Understand No-Result Cases

No results may mean several different things:

• no resource matches the query;
• filters are too narrow;
• the resource exists but has not been indexed yet;
• the Discovery node is not authorized for that domain;
• the resource is revoked, suspended, or superseded;
• semantic indexing is still catching up;
• the resource metadata is too vague to match well.

Try broadening the query, removing optional filters, checking official service status, or using a different authorized Discovery endpoint if appropriate.

No-result troubleshooting is easier if you keep the pipeline in mind. If the resource was never Root-accepted, Discovery cannot find it. If it was accepted but not indexed, a better query will not help yet. If it is indexed but semantically hard to match, better descriptions and tags may help in the next version.

Further Reading

• Resource registration and discovery guide
• IETF draft: Efficient Agent Discovery profile
• GRAIL semantic discovery paper