---
title: "Why Agents Need a Capability Taxonomy, Not Just Tags"
summary: "A capability taxonomy offers structured, precise classification for AI agents, improving discovery and query mapping beyond simple tags."
published: 2026-11-11T00:33:12.247Z
data_as_of: 2026-11-11T00:33:04.810Z
kind: guide
tags: [capability-taxonomy, ai-agents, mcp, wellknown, api, discovery]
canonical: https://wellknown.network/blog/capability-taxonomy-for-machines
facts: https://wellknown.network/blog/capability-taxonomy-for-machines/facts.json
---

# Why Agents Need a Capability Taxonomy, Not Just 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/search` or call the MCP tool `search_agents`.
- To resolve a specific agent’s details, use `https://wellknown.network/api/v1/resolve` or the MCP tool `resolve_agent`.
- To get detailed information about an agent by ID, call `https://wellknown.network/api/v1/agents/{id}` or the MCP tool `get_agent`.
- To check the live status of an agent, use `https://wellknown.network/api/v1/agents/{id}/status` or the MCP tool `check_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/submit` or the MCP tool `submit_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/search` and `/api/v1/submit`.
- Do not confuse MCP tool names with URLs; tools like `search_agents` are 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.
