Why Agents Need a Capability Taxonomy, Not Just Tags
A capability taxonomy offers structured, precise classification for AI agents, improving discovery and query mapping beyond simple tags.
Why a Capability Taxonomy Matters
AI agents and tools are increasingly diverse and complex, making simple tags insufficient for accurate classification and discovery. A capability taxonomy provides structured slugs, aliases, and derivation with confidence scores, enabling more precise and meaningful categorization. This structured approach helps map user queries directly to capabilities, improving search relevance and interoperability among agents.
How Wellknown Sees Your Resource
Wellknown indexes over 88,909 records, with 28,572 observed live as of 2026-11-11. It distinguishes between declared metadata—what publishers state—and observed status—what Wellknown measures by endpoint checks. Statuses include live (latest check succeeded within 24 hours), recently observed, unavailable, and unknown. This distinction ensures that capability taxonomies are grounded in both publisher intent and real-world availability.
Step-by-Step How to Use Wellknown’s API and MCP Tools
Wellknown provides HTTP API endpoints and MCP server tools to interact with its index and capability data. These are the exact paths and tools you can use:
- To search for agents by capability or other criteria, send requests to
https://wellknown.network/api/v1/searchor call the MCP toolsearch_agents. - To resolve a specific agent’s details, use
https://wellknown.network/api/v1/resolveor the MCP toolresolve_agent. - To get detailed information about an agent by ID, call
https://wellknown.network/api/v1/agents/{id}or the MCP toolget_agent. - To check the live status of an agent, use
https://wellknown.network/api/v1/agents/{id}/statusor the MCP toolcheck_status. - To list capabilities exposed by agents, use the MCP tool
list_capabilities. - To submit or update agent records, use
https://wellknown.network/api/v1/submitor the MCP toolsubmit_agent. - For index statistics, call the MCP tool
index_stats.
All these endpoints and tools are provided by Wellknown and should be called as-is; do not construct additional paths or URLs.
What Changes Once a Capability Taxonomy Is Implemented
Implementing a structured capability taxonomy allows agents to be discovered more precisely and reliably. Queries map directly to capabilities rather than ambiguous tags, improving search accuracy and interoperability. Publishers gain verified control over their records through claim proofs such as DNS TXT records at _wellknown.YOUR-DOMAIN, a .well-known/wellknown-verify.txt file, or a .wellknown-verify file at the repository root. This verification enhances trust and data integrity in the index.
Common Mistakes to Avoid
- Do not rely solely on tags; they lack structure and confidence measures.
- Avoid inventing or guessing API paths; use only the documented endpoints such as
/api/v1/searchand/api/v1/submit. - Do not confuse MCP tool names with URLs; tools like
search_agentsare called over the MCP protocol, not via HTTP paths. - Ensure claim proofs are correctly implemented to verify ownership and avoid unverified records.
- Remember that an observed status of unknown is not a failure but indicates no checks have run or no network endpoint exists.
For comprehensive documentation, consult Wellknown’s official docs at https://wellknown.network/docs and related pages.
This data is a snapshot as of 2026-11-11T00:33:04.810Z.
A fact sheet was computed from the index at the time above. A language model drafted the text from that sheet only; the draft was accepted because every figure in it appears in the sheet and every record link resolves. Read the sheet at facts.json or the article as article.md.