Taxonomy and tagging
Where a card's tags come from, how the concept vocabulary is built, and how to argue with a tag.
Tags are one of the most contested parts of Magic, and they are also what lets the app search and reason about cards. Whether something counts as "ramp", and what kind of ramp, is often a judgement. People disagree, and the disagreement is legitimate. This page says exactly how a tag gets attached, so you can tell whether a tag you dislike is a bug, a rule you would have drawn differently, or a genuinely hard call.
The vocabulary itself lives in the app: /search/tags for the
tags, and /search/concepts for every game concept with its
definition and rule citations. This page is the mechanism.
The vocabulary
game_concepts holds 833 rows. Three
properties describe each one, and they are independent of each other.
source records where the concept came from.
| Source | Concepts | Meaning |
|---|---|---|
official | 726 | Defined in the Comprehensive Rules, with the rules it cites |
community | 107 | Deck-building vocabulary the rules have no word for, such as "ramp" or "board wipe" |
Both sources behave identically everywhere downstream. The column records provenance, so a definition can be traced back to a rule where one exists.
taggable decides whether a concept is used to classify cards. 152 of the
833 are taggable, and they come from both sources: 45 official concepts are
taggable alongside all 107 community ones. The remaining 681 exist to be looked
up and to be cited.
category groups concepts by what kind of thing they are.
| Category | Concepts | Taggable |
|---|---|---|
general | 490 | 5 |
keyword_ability | 181 | 40 |
synergy_theme | 46 | 46 |
functional_role | 32 | 32 |
keyword_action | 31 | 0 |
named_token | 13 | 0 |
hate | 12 | 12 |
zone | 11 | 0 |
removal_subtype | 7 | 7 |
combat_trait | 6 | 6 |
ramp_subtype | 4 | 4 |
The split falls along one line. Categories describing how a card functions in a deck are taggable end to end. Categories describing Magic's own machinery, such as zones and keyword actions, are reference only: "battlefield" is worth defining and a poor label to hang on a card.
How the vocabulary is built
Every concept is embedded once its definition is written, and the embedding is what makes the vocabulary usable by similarity rather than by exact match.
Re-running pnpm embed:taxonomy is what publishes an edited definition to
everything that matches on meaning. A concept whose definition changed but whose
embedding did not will still match the old wording.
How a card gets tagged
Four sources write to
card_concept_associations, and
every row records which one produced it.
Mechanical. Pattern matching driven by the 148 rules in
tag_detection_rules. Each rule is a
set of oracle-text regexes, keyword matches and type matches, plus the negative
patterns that suppress false positives. Confidence is fixed at 1.0, because a
rule either matched or it did not.
Vector. For each taggable concept, cards whose own embeddings sit closest to the concept embedding are associated, with the raw cosine similarity stored as the confidence. This catches cards that mean the right thing without using the expected words.
Model. A language model deciding the hard cases. This is the smallest automated pass by a wide margin.
Manual. Eight associations were entered by hand, across ramp, looting,
evasive, defensive, aggressive and tribal. The table records the source
so a hand-entered row can be told apart from a generated one.
Associations also carry a relationship. tag means the card is an
instance of the concept. context means it merely mentions it. A card reading
"target opponent sacrifices a creature" is removal; a card reading "whenever a
creature dies" is about creatures dying. Only tag rows reach tag: search,
and conflating the two would make it much worse.
What that actually produces
Counts as of 2026-08-27:
| Pass | Associations | Share |
|---|---|---|
| Mechanical | 146,166 | 82.7% |
| Vector | 30,400 | 17.2% |
| Model | 171 | 0.10% |
| Manual | 8 | 0.005% |
83% of tagging is deterministic pattern matching. The model accounts for roughly one association in a thousand, applied where the rules cannot reach. To predict whether a card will carry a tag, read its detection rule.
Where the embeddings are used
Tagging is one of three places the same vectors do work. All three use cosine similarity, and all three degrade to something usable when a vector is missing.
| Use | Compares | Effect |
|---|---|---|
| Vector tagging | Concept embedding against card embeddings | Writes associations |
| Search re-ranking | Query intent against card embeddings | Orders results by relevance |
| Concept resolution | Message against concept embeddings | One of three paths that decide what a question is about |
Card embeddings are generated separately by pnpm embed:cards, and are Voyage
voyage-3 truncated to 256 dimensions. A card added since the last run has no
vector, so it cannot be reached by the vector tagging pass and it sorts last in
re-ranked search results.
How tag: search connects
tag:removal filters cards.tags, a denormalized array on the
card, so it never joins through the associations table. The array holds the
tag relationship only, and context rows are excluded by design.
A trigger keeps the array equal to the associations, so a tagging pass reaches search in the same transaction it writes. A tag a maintainer has removed is left out whichever pass asserts it.
Tag values are validated against the vocabulary. An unknown tag is rejected with suggestions. That matters more for the AI than for you: a model that invents a plausible tag name gets an error and a correction, where an empty result set would read as "no such cards exist".
Disagreeing with a tag
Three cases, with different fixes:
- The card does not match the rule. A bug in the detection rule, usually a missing negative pattern.
- The card matches the rule but should not be tagged. The rule is too broad. Same fix, harder call.
- The card is tagged correctly and you would draw the line elsewhere. A disagreement about the vocabulary. "Is a Rampant Growth effect ramp when it fetches a land, or only when it produces mana?" has no correct answer, only a chosen one.
To report any of them, open the card's page and use the suggest-a-correction control under the tag. Every tag on a card detail page carries one. It takes the card, the tag and what you think it should be.
The first two cases are worth reporting as bugs. The third is worth arguing about, and the answer belongs in the vocabulary.
Scryfall tags
Scryfall's community tagging system is far larger and covers the long tail well.
It is not imported here and tag: does not reach it. Every tag in this system
traces back to one of the four sources above.