Skip to content

Discord commands and ratings

The commands work in the one server the operator registered them in, or in every server the bot is in when they are registered globally. Registered globally, /card, /rule, /help, /license and /forget also work in a DM with the bot. /judge and /judge-private work only in a server.

Ask in plain language. Nicknames work (“bob”, “goyf”, “snappy”, “t3feri”). The alias list is data/aliases.yaml in the repository, and pull requests adding to it are welcome. Use brackets like [[Full Card Name]] to avoid ambiguity. A bracketed name matches only the card with that exact name (current or printed, including one face of a split or double-faced card), or the one card a listed nickname stands for ([[bob]]). Anything else in brackets, such as a near miss, is offered back as a choice rather than corrected. Answers take twenty to forty-five seconds. The bot acknowledges at once and edits the reply in.

A Discord reply to /judge asking when a player first gets priority. The answer runs to two paragraphs with rule numbers inline, six rule quotations follow in an embed with the confidence and CR version, and three rating buttons sit beneath.

The reply opens with a non-pinging @you asked: header, then the ruling, then a citation per line. Rule citations link to the rule on the Yawgatog mirror of the Comprehensive Rules. Rulings and Oracle text link to the card on Scryfall. The footer names the cards the question was resolved to, so you can check that “bob” was taken to mean Dark Confidant. It also gives the model’s confidence and the CR version it answered from.

Scryfall lists previewed cards weeks before their set comes out, and the judge answers questions about them. Until the set’s Comprehensive Rules update is published (usually a week before release), the rules may not have the card’s new keywords or creature types. An answer about such a card opens with a note naming it:

Note: This question references unreleased cards. The Comprehensive Rules might not have enough information to properly evaluate one or more of them (Seven of Nine).

During prerelease week, once the set’s update is loaded and mentions every type and keyword on the card, the note is not shown. An answer about a card that was not out yet is never shown to the model as an example, even after the card’s release.

If a name could mean several cards (“Tibalt”, “Emrakul”) you get a did you mean…? row of up to five buttons. Only the person who asked can pick, once, within ten minutes. A pick still works after the bot restarts, because the message holds the question. That is also why a question is at most 1300 characters. If a name matches nothing, the reply says which and suggests [[Full Card Name]]. Tournament-policy and price questions are declined after the cheap classification step, before the expensive synthesis call.

A Discord reply asking which Tibalt was meant: a numbered list of three cards, and a button for each.

Ask a follow-up in the same channel and the bot sees the recent question-and-answer pairs from that channel as history, so “what if it had flash?” works.

Each member can ask a limited number of questions per window (six per ten minutes unless the operator changed JUDGE_USER_LIMIT). Past it, the bot tells the asker alone how long is left. A question turned away as “busy” or over the limit does not count. Any other question does, answered or not. Picking a card from a “did you mean…?” row does not count again, and /card and /rule are never limited.

/judge-private asks the same way as /judge and shows the answer to you alone, as Discord’s “Only you can see this” message. A private answer stands by itself:

  • It reads no channel history, so it cannot be a follow-up, and no later question in the channel reads it.
  • It is stored like any other call, with your user id and username, marked private. Only the operator can see it. It is never shown publicly and never becomes an example for a later question. It is still sent to the model provider and leaves the same log lines as any question.
  • It has rating buttons, which only you see.
  • “Did you mean…?” still works, privately.

Discord fixes who sees a reply when the bot acknowledges the command, so a private answer cannot be made public afterwards. Ask again with /judge.

Lookups from the bot’s database. They call no model, cost nothing and answer at once.

  • /card takes a name or nickname, resolved as /judge resolves it, and shows every face’s mana cost, type line and current Oracle text, then the card’s rulings, newest first. The title links to the card on Scryfall. A name that could mean several cards lists them.
  • /rule takes a rule number: 702.19 (the rule with its sub-rules and examples), 702.19b (one sub-rule) or 702 (the section, as many whole rules as fit). The title links to the rule on the Yawgatog mirror, and the footer is the CR version. A rule longer than an embed is cut, with a note to ask for one sub-rule.

Both post in the channel.

The /card reply for Dark Confidant: the name as a link, the mana cost drawn as symbols, the type line, the Oracle text, and two rulings, each with its date.

Every answer has three buttons: Incorrect, Partially correct, Correct. A rating’s score changes only which past answers are shown to the model as examples when a similar question comes in. Scores are smoothed (a Bayesian mean with a prior of “partially correct” and a weight of three votes), so one early vote cannot swing an answer’s standing. Answers rated below 1.5 with at least five votes are excluded, and so is one a judge rated Incorrect (see below) or one about a card that was not out yet when it was answered.

  • Correct is recorded at once.

  • Partially correct and Incorrect open a short form, which only you see:

    • What kind of problem? (required): wrong conclusion, missed part of the question, a citation doesn’t support it, wrong card, misread the question, shouldn’t have refused, outdated, or other.
    • What’s wrong and The right answer (both optional, up to 1000 characters each).

    Submitting it records the rating with its reason. Closing the form records nothing.

  • The reason goes to the operator’s feedback queue, beside the question, the answer, its citations and cards, so they can fix what went wrong (a card note, a nickname, a prompt). The model never reads it. When the operator sets JUDGE_PUBLIC_FEEDBACK=true, the reason is also shown on the answer’s public web page, without your name; the form’s hints and the confirmation say so. A reason the operator dismisses is taken off the public page.

  • Rating an answer you already rated asks first: “You already rated this answer Partially correct (Wrong card). Replace it with Incorrect?” Replace goes on to the new rating’s form, or records Correct; Keep changes nothing and says what is on record. Pressing Correct again on an answer you rated Correct says it is already recorded.

After an Incorrect rating, the confirmation names the operator, who reads every reason given. When the instance’s source is on GitHub, it also links that repository’s Wrong or unhelpful ruling issue form, for a wrong answer the project should hear about.

Members holding the server’s judge role (JUDGE_ROLE, default Judge) rate with an override. The most recent judge rating replaces the crowd’s score for that answer, so a judge’s Incorrect excludes it at once, however few votes it has. The rules always outrank examples. Prior answers are rendered after the CR material and labeled with their rating, and the model is told they are precedent, not authority.

A past answer is retired automatically when its citations stop holding against the current rules, rulings or Oracle text (a new CR release, an erratum). It comes back if the text is restored.

Two replies, both ephemeral, so only you see them:

  • what the bot does and how to ask, ending with a Data. list: the Comprehensive Rules release loaded, when the data was last refreshed, and whether the latest refresh failed
  • what it stores, that a question not asked private may be listed on the web app’s public feed (unless the operator set JUDGE_FEED=false), then the same notice as /license: where the source is and who runs this instance.

The source offer, shown only to you:

  • the repository holding this instance’s source code
  • the commit it was built from, linked into the repository
  • the licence (AGPL-3.0-or-later) and the copyright
  • the Discord username of whoever runs this instance, and their support address if they set one.

An unmodified build names the upstream repository. An operator running a modified version points it at their fork with JUDGE_SOURCE_URL. The username is JUDGE_OPERATOR_DISCORD, which the bot does not start without.

While the instance migrates its database for a major release, usually a minute or two, /judge answers with your question and a Retry button instead of an answer. Press it once the upgrade is done to ask the same question again; only you can press it, and it counts as one question. /card, /rule, /forget and the rating and “did you mean?” buttons say the bot is being upgraded and change nothing. /help and /license work as usual.

Deletes every rating you have recorded, removes your user id and username from every question you asked, and anonymizes every failed call of yours. It tells you how many of each there were.

  • A question you asked in the channel keeps its text, which the channel saw, and is shown as asked anonymously, on the web app’s feed too.
  • A private question keeps its time and thread. Its question and answer are replaced, and what it cited and which cards it was about are removed.
  • A failed call keeps its time, thread and whether it was private. Its question, error and the model’s text are replaced.