MineCode MCP
Provides search capabilities for Mojira, the Minecraft bug tracker running on Jira, allowing querying of bug reports by project, status, and resolution.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MineCode MCPsearch the wiki for how to summon a custom mob"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MineCode MCP
Version-accurate Minecraft data for AI assistants
MineCode is a local Model Context Protocol (MCP) server that gives AI assistants like GitHub Copilot and Claude real-time access to version-accurate Minecraft data, documentation, vanilla presets, and your Minecraft logs.
Written for a hackathon about MCP sponsored by dust, alpic, and others. Prototyped using the worst ai model ;-; (note I rewrote it now it is actually viable). Please star if you'd like to help out, and open issues for anything broken.

π― The problem this solves
AI assistants get Minecraft syntax wrong constantly, and they do it confidently. The reason is simple: Minecraft's datapack format changed substantially and repeatedly, and every model's training data is older than the current game.
1.20.5 replaced item NBT with typed components. Old NBT is now a hard parse error.
1.21 renamed every datapack folder to singular (
advancements/βadvancement/). A pack with the old names loads with no error and no content β it silently does nothing.1.21.2 dropped the
generic.prefix from every attribute ID.1.21.4 turned
custom_model_datafrom an integer into an object.1.21.5 made text components strictly typed.
minecraft.wiki documents only the latest version, so consulting it for an older pack actively makes this worse.
MineCode attacks this from four directions:
minecraft_start_sessionβ detects the target version frompack.mcmetabefore any code is written, so nothing downstream is guessing.get_technical_changesβ returns what actually changed between two versions, from misode/technical-changes plus a curated table of the traps agents fall into most.get_command_usage/validate_commandβ command syntax compiled from the game's own Brigadier grammar, and a parser to check the agent's output against it.Honest tool descriptions β every wiki tool states up front that it covers the latest version only, and names the version-exact alternative.
Related MCP server: mcplens
π Installation
Requires Python 3.10 or newer. Check with python --version (Windows: py --version).
Windows
py -m pip install --upgrade pip
py -m pip install minecode-mcpVerify:
py -m minecode.server --help 2>$null; py -c "import minecode; print('ok')"If
pyis not recognised: Python isn't installed or wasn't added to PATH. Reinstall from python.org with "Add python.exe to PATH" ticked. Avoid the Microsoft Store build β it sandboxes file access, which breaks readingpack.mcmetaand Minecraft logs from arbitrary paths.
macOS
python3 -m pip install --upgrade pip
python3 -m pip install minecode-mcpIf your Python is Homebrew-managed you'll hit error: externally-managed-environment. Use a venv (see below) or pipx:
brew install pipx && pipx install minecode-mcpLinux
python3 -m pip install --upgrade pip
python3 -m pip install minecode-mcpMost modern distributions (Arch, Debian 12+, Ubuntu 23.04+, Fedora) mark the system Python as externally managed and will refuse the command above. That protection is correct β don't override it with --break-system-packages. Use one of:
# Option A: pipx β recommended, isolated but still on PATH
sudo pacman -S python-pipx # Arch
sudo apt install pipx # Debian/Ubuntu
sudo dnf install pipx # Fedora
pipx install minecode-mcp
# Option B: user install
python3 -m pip install --user minecode-mcp
# Option C: a venv you point the client at (see Configuration)Isolated install (any platform)
Works everywhere and never touches system Python. Note the absolute path it prints β you'll need it for the client config.
# Linux / macOS
python3 -m venv ~/.minecode-venv
~/.minecode-venv/bin/pip install minecode-mcp
echo ~/.minecode-venv/bin/minecode# Windows
py -m venv $HOME\.minecode-venv
& $HOME\.minecode-venv\Scripts\pip.exe install minecode-mcp
Write-Output "$HOME\.minecode-venv\Scripts\minecode.exe"Upgrading and uninstalling
pip install --upgrade minecode-mcp # or: pipx upgrade minecode-mcp
pip uninstall minecode-mcp # or: pipx uninstall minecode-mcpUpgrading doesn't clear the response cache. That's intentional β version-pinned data can't go stale. To clear it anyway, call the cache_status tool with clear=true, or delete the directory shown by cache_status.
Which Python am I actually using?
The single most common setup failure is installing into one interpreter and pointing the client at another. When in doubt, get the absolute path and use it verbatim in your client config:
python3 -c "import sys; print(sys.executable)" # Linux/macOS
py -c "import sys; print(sys.executable)" # WindowsβΆοΈ Running the server
MineCode is an MCP server, not an app you sit in front of. It speaks JSON-RPC over stdin/stdout and is normally launched by your AI client, not by you. You rarely need to start it manually β but you do need to know how, because that's how you check the install before wiring up a client.
The two ways to launch it
minecode # console script, installed by pip
python -m minecode.server # module form β identical, works even if the script isn't on PATHOn Windows use py -m minecode.server.
What "working" looks like
Running it directly looks like a hang. That is correct:
$ minecode
[INFO] Loaded assistant preprompt from .../assistant_preprompt.txt
[INFO] Starting MineCode MCP server
[INFO] MineCode MCP server starting (stdio)
[INFO] Registered 30 tools, 1 prompts, 2 resourcesβ¦and then nothing. The server is waiting for JSON-RPC on stdin. This is a healthy server, not a freeze. Press Ctrl+C to stop it.
The line that matters is Registered 30 tools. If you see it, the install is good. Logs go to stderr, so they never corrupt the protocol stream on stdout.
Verifying the install without a client
python -c "
from minecode import tools
print(f'{len(tools.TOOLS)} tools, {len(tools.HANDLERS)} handlers')
assert {t.name for t in tools.TOOLS} == set(tools.HANDLERS)
print('registry consistent')
"To exercise a tool without any MCP client at all:
python -c "
from minecode import handlers
r = handlers.handle_get_command_usage('1.21.4', 'give')
print(r['usage'])
"Expected: ['/give <targets> <item>', '/give <targets> <item> <count>']
A full protocol handshake, if you want to be thorough:
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| python -m minecode.server 2>/dev/null | tail -1 | head -c 300Normal usage
Configure your client (next section), then restart it. The client spawns the server itself and keeps it alive for the session. From then on you just talk to your assistant β start with something like "set up my datapack and tell me what version it targets", which triggers minecraft_start_session.
Troubleshooting
Symptom | Cause and fix |
| The script isn't on PATH. Use |
| Wrong interpreter. The client's |
|
|
|
|
| You have mcp 2.x. Run |
Server starts, client shows no tools | Client config points at a different Python or a stale install. Restart the client fully β most only read MCP config at startup |
Everything hangs with no output | Expected when run directly, see above. If it happens inside a client, check the client's MCP logs |
Tools are slow the first time | Normal β first call fetches and caches upstream data. Later calls are near-instant |
Suspect stale data |
|
βοΈ Configuration
Claude Desktop / Claude Code
{
"mcpServers": {
"minecode": {
"command": "minecode"
}
}
}OS | Config path |
Windows |
|
macOS |
|
Linux |
|
VS Code (GitHub Copilot)
Add to User Settings (Ctrl+Shift+P β "MCP: Open User Configuration"), or create .vscode/mcp.json in your workspace:
{
"servers": {
"minecode": {
"type": "stdio",
"command": "minecode",
"args": []
}
},
"inputs": []
}The minecode script is installed alongside the package and already points at the right interpreter, so this form works for pipx, venv, and --user installs alike.
The module form is equivalent only if the package is importable from whichever python the client resolves:
{
"servers": {
"minecode": {
"type": "stdio",
"command": "python",
"args": ["-m", "minecode.server"]
}
},
"inputs": []
}β οΈ VS Code spawns the server with a bare
pythonfromPATHβ not your selected Python interpreter, and not a pipx or venv environment. With a pipx install this fails withNo module named minecode, since the package lives in pipx's own venv. Use"command": "minecode"above, or the absolute interpreter path from the next section.
On Windows use
"command": "py"for the module form.pyis the Windows launcher and does not exist on macOS or Linux.
If minecode isn't on PATH
Common with venv, pipx, and --user installs. Give the absolute path to the interpreter that has the package, and let it run the module:
{
"mcpServers": {
"minecode": {
"command": "/home/you/.minecode-venv/bin/python",
"args": ["-m", "minecode.server"]
}
}
}Platform | Typical interpreter path |
Linux / macOS venv |
|
Windows venv |
|
pipx (any) | run |
Linux |
|
Get the exact path with python3 -c "import sys; print(sys.executable)" from the environment where you installed it.
Windows JSON: backslashes must be escaped β
C:\\Users\\...β or use forward slashes, which also work.
Restart the client fully after editing the config. Most MCP clients read it only at startup, so a reload isn't enough.
π οΈ Tools
Start here
Tool | Description |
| Call first. Detects the target version from |
Version correctness
Tool | Description |
| What changed between two versions β the fix for outdated syntax knowledge |
| Scan a command or JSON for syntax that's wrong for a version |
| Check folder layout β catches the silent 1.21 folder rename failure |
| Read |
| Map between the two |
| Which versions have changelog coverage |
Commands
Tool | Description |
| Readable, version-exact syntax compiled from the Brigadier tree |
| Parse a command against the real grammar; reports the failing token |
Spyglass (authoritative, version-exact)
Tool | Description |
| Versions with data/resource pack formats |
| Valid IDs per registry per version |
| Block state properties and defaults |
| Command names, or one command's tree plus rendered usage |
| Find mcdoc symbol paths by keyword |
| One data structure's field-level schema |
Misode (real vanilla data)
Tool | Description |
| Real vanilla JSON for a version β the best shape reference available |
| Preset IDs for a generator type |
| Loot tables by category |
| Recipes by type |
| Web generator links to show the user |
| Versions with data available |
Minecraft Wiki β β οΈ latest version only
Tool | Description |
| Search pages |
| Page summary, or full content with |
| Prose about a command β not a syntax reference |
| Command list |
| Pages in a category |
Other
Tool | Description |
| Bug tracker search (filters by project, not version) |
| Local Minecraft logs, with |
| Inspect or clear the response cache |
Prompts and resources
Kind | Name | Description |
Prompt |
| Loads the development methodology |
Resource |
| Same methodology, attachable as context |
Resource |
| The curated migration table as JSON |
π‘ Example prompts
"Set up my datapack for 1.21.4 and tell me what changed since 1.20.4"
"Why does my datapack do nothing on 1.21?"
"What's the correct
/givesyntax with enchantments for this pack's version?"
"Convert this 1.20.4 loot table to 1.21.4"
"Check my Minecraft logs for errors"
π§ How version knowledge works
Two layers, deliberately:
The curated table (minecode/knowledge/migrations.json) holds ~16 breaking changes as concrete before/after code pairs β the ones where a model's training data actively fights the correct answer. It's small, offline, instant, and every entry carries a verify_with field naming the tool that confirms it. It is a fast first-pass signal, never an authority.
The changelog (misode/technical-changes) is exhaustive and community-maintained across every snapshot. get_technical_changes queries it live.
This split is on purpose. A hand-written document covering every version's changes would be stale the day it was written, impossible to keep current against Minecraft's snapshot cadence, and far too large to fit in context. Keeping the curated layer small and querying the maintained source for everything else is what makes it sustainable.
Adding a migration
Add an entry to migrations.json:
{
"id": "kebab-case-id",
"title": "Short description",
"changed_in": "1.21.5",
"affects": ["give", "item"],
"severity": "breaking",
"confidence": "high",
"before": "the old syntax",
"after": "the new syntax",
"explanation": "What changed and what happens if you get it wrong.",
"detect": [
{"pattern": "regex", "kind": "command|json|path|any", "message": "What to do instead"}
],
"verify_with": "get_technical_changes(from_version='1.21.4', to_version='1.21.5')"
}Then add tests to tests/test_knowledge.py β one for detection and one for the false-positive case. A checker that flags correct modern syntax trains the agent to ignore it, which is worse than having no checker at all.
π§βπ» Development
Setup
Linux / macOS
git clone https://github.com/AnCarsenat/minecode-mcp.git
cd minecode-mcp
python3 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"Windows (PowerShell)
git clone https://github.com/AnCarsenat/minecode-mcp.git
cd minecode-mcp
py -m venv venv
.\venv\Scripts\Activate.ps1
py -m pip install --upgrade pip
py -m pip install -e ".[dev]"If activation is blocked:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
The -e (editable) install means source edits take effect immediately β no reinstall between changes. But your MCP client must point at this venv's interpreter, not a system one, or you'll be testing the published package instead of your working copy.
Everyday workflow
pytest -m "not network" # ~0.4s β run before every commit
python -m minecode.server # smoke test; "Registered N tools" then a hang is correctpytest -m network # live API tests, hits volunteer-run services
pytest tests/test_knowledge.py -v # one file
pytest -k "migration" -v # by name
pytest -m "not network" --lf # only last-failedPlease don't run the network suite in a loop β Spyglass, misode and minecraft.wiki are volunteer-funded. The offline suite covers the logic; the network suite only checks that upstream response shapes haven't changed.
Testing against a real datapack
The most valuable check, and how the redirect and backtracking bugs were found:
python - <<'EOF'
import pathlib
from minecode import handlers
PACK = pathlib.Path("path/to/your/datapack")
info = handlers.handle_minecraft_start_session(str(PACK))
version = info["target_version"]
print("target:", version, "| multi-version:", info["multi_version"])
print("structure:", handlers.handle_check_pack_structure(str(PACK))["issue_count"], "issues")
bad = 0
for f in PACK.rglob("*.mcfunction"):
for n, line in enumerate(f.read_text(errors="ignore").splitlines(), 1):
line = line.strip()
if not line or line.startswith(("#", "$")):
continue
result = handlers.handle_validate_command(line, version)
if not result.get("valid"):
bad += 1
print(f"{f.name}:{n} {line[:80]}\n -> {result.get('error')}")
print("invalid commands:", bad)
EOFA false positive here is a bug worth reporting β a validator that cries wolf gets ignored, which is worse than having none.
Environment variables
Variable | Effect |
| Disable the disk cache. Use when testing scraper changes, and always in CI |
| Override the cache location |
Project layout
server.py is wiring only (transport, dispatch, prompts, resources). tools.py holds schemas plus the nameβhandler registry. handlers.py holds behaviour. scrappers/ talks to the outside world. Nothing else should make HTTP calls.
Adding a tool
Write
handle_<name>inhandlers.py. Return a dict withsuccess, never a bare string.Add a
TooltoTOOLSintools.py.Add the entry to
HANDLERSin the same file.pytest -m "not network"
Step 3 is not optional and not forgettable β tools.py asserts at import time that TOOLS and HANDLERS match exactly, so a missing entry fails immediately rather than months later. That assertion exists because four working changelog functions sat unreachable in misode.py for exactly that reason.
Description guidance, learned from what actually goes wrong:
Say when to call it, not just what it does. Agents match situation to description.
Put limitations first. A caveat at the end isn't read in time to change the decision.
Name the better tool when one exists β "use X instead for Y" prevents the wrong choice a neutral description invites.
Adding a version migration
See How version knowledge works. Every entry needs two tests: one proving detection fires, one proving it does not fire on correct modern syntax.
Code conventions
Handlers return dicts; the dispatcher does the JSON encoding
Every
versionparameter goes throughpackmeta.resolve_versionfirstScrapers go through
cache.cached_fetchNever return
[]for a failure β an empty list reads as a real "none found" answer. Raise insteadReport truncation explicitly. A silently capped list reads as complete
On the
mcpdependency: pinned to>=1.25.0,<2. mcp 2.0 removed the low-level decorator API this server is built on; installing 2.x raisesAttributeErrorat import. Migrating to the 2.xMCPServerAPI is open work β PRs welcome.
Contributing
Branch off main, keep commits scoped to one concern, run pytest -m "not network" before pushing. CI runs the offline suite on Python 3.10/3.11/3.12 for every PR; live tests run nightly.
π¦ PyPI publishing
Publishing uses Trusted Publishing (OIDC). There is no API token anywhere β no PYPI_API_TOKEN secret to create, paste, rotate, or leak. GitHub proves its identity to PyPI directly.
One-time setup
1. Create the GitHub environment
Repo β Settings β Environments β New environment β name it exactly pypi.
Optionally add yourself under "Required reviewers". That makes every publish need a manual click β a good safety net, since a tag push would otherwise publish immediately and a version number burned on PyPI can never be reused.
2. Register the publisher on PyPI
Log in at pypi.org.
If
minecode-mcpalready exists: go to the project β Manage β Publishing.For a brand-new project: Account settings β Publishing β Add a pending publisher.
Fill in exactly these values:
Field | Value |
PyPI Project Name |
|
Owner |
|
Repository name |
|
Workflow name |
|
Environment name |
|
The workflow filename and environment name must match character for character. This is the most common place setup goes wrong, and the resulting error is an opaque 403.
That's it. No token is generated and nothing is pasted into GitHub.
Releasing
β οΈ Step 1 is bumping the version in
pyproject.toml. Do not skip it.A version number on PyPI is permanent. Once
0.2.0is published, that number can never be reused or overwritten β even if you delete the release. A bad publish can only be followed by a new version, never a replacement. Re-tagging an already-published version fails at the upload step.
1. Bump the version. Edit version in pyproject.toml:
version = "0.2.1" # was 0.2.0Which digit to move:
Change | Bump | Example |
Bug fix, docs, internals β nothing user-visible breaks | patch |
|
New tools, new parameters β existing setups keep working | minor |
|
Tools removed or renamed, parameters removed β existing configs break | major-ish |
|
(0.2.0 was a minor bump because it removed two tools and renamed one.)
2. Commit, tag, and push. The tag must be v + the exact version:
git add pyproject.toml
git commit -m "Release 0.2.1"
git tag v0.2.1
git push origin main --tags3. Approve the deployment. The workflow builds, then pauses. Go to the
Actions tab β the running Publish to PyPI run β Review deployments
β tick pypi β Approve and deploy. GitHub also emails you an approve link.
Publishing takes about 30 seconds after approval.
What the workflow checks before it will publish
The tag matches
pyproject.tomlβ this is the safety net for a forgotten bump. Taggingv0.2.1whilepyproject.tomlstill says0.2.0fails the build withTag v0.2.1 does not match pyproject.toml version 0.2.0, and nothing is publishedOffline test suite passes
Wheel and sdist build
twine checkon the metadataThe preprompt, config, and migration table are actually inside the wheel
If any of these fail, the approval button never appears β there is nothing to approve.
If you forgot to bump
The build fails at step 1 and nothing ships. Recover by deleting the tag, bumping properly, and re-tagging:
git tag -d v0.2.1
git push origin :refs/tags/v0.2.1
# bump pyproject.toml, commit, then tag againThis is safe precisely because nothing was published.
Optional: TestPyPI first
Register a second pending publisher at test.pypi.org with the same values but environment testpypi, create a matching GitHub environment, then add this job to publish.yml:
publish-test:
needs: build
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
environment:
name: testpypi
permissions:
id-token: write
steps:
- uses: actions/download-artifact@v4
with: { name: dist, path: dist/ }
- uses: pypa/gh-action-pypi-publish@release/v1
with:
repository-url: https://test.pypi.org/legacy/
skip-existing: trueThis catches packaging errors before they reach real PyPI, where a version number is burned permanently β you can't re-upload 0.2.0 after a bad publish, only bump to 0.2.1.
Troubleshooting
Symptom | Cause |
| Publisher fields don't match, or |
Workflow doesn't run | Tag doesn't match |
"Tag does not match pyproject" | You tagged without bumping the version |
Publish hangs | Required reviewer is set; approve it in the Actions tab |
π Project structure
minecode-mcp/
βββ minecode/
β βββ server.py # Transport, dispatch, prompts, resources
β βββ tools.py # Tool schemas + name->handler registry
β βββ handlers.py # Tool behaviour
β βββ brigadier.py # Command tree rendering and validation
β βββ packmeta.py # pack.mcmeta reading, version resolution
β βββ cache.py # Disk cache
β βββ knowledge/
β β βββ __init__.py # Version comparison, syntax checking
β β βββ migrations.json # Curated breaking changes
β βββ preprompts/
β β βββ assistant_preprompt.txt
β βββ config/
β βββ scrappers/
β βββ spyglass.py # Version-exact registries, commands, mcdoc
β βββ misode.py # Vanilla presets + technical changelogs
β βββ minecraftwiki.py # Wiki (latest version only)
β βββ mojira.py # Bug tracker
β βββ minecraft_logs.py # Multi-launcher log reader
βββ tests/
βββ example/crystal_dimension/
βββ pyproject.tomlπ Data sources
Source | Role |
Registries, command trees, mcdoc β version-exact | |
Vanilla presets per version | |
Per-version technical changelogs | |
Concepts and mechanics (latest version only) | |
Bug tracker |
Spyglass, misode, and the wiki are volunteer-run. MineCode caches aggressively β version-pinned data permanently, since it cannot change β to keep request volume low. Please don't disable the cache in automated setups.
π License
MIT β see LICENSE
Available Tools
19 toolsget_logsA
Get Minecraft instance logs. Auto-detects launcher or specify 'default', 'prism', or 'tlauncher'. For Prism, optionally specify an instance name. Returns the latest log file content with configurable line count.
| Name | Required | Description | Default |
|---|---|---|---|
| launcher | No | Launcher type: 'default', 'prism', 'tlauncher', or omit for auto-detect | |
| instance | No | Instance name (for Prism Launcher only) | |
| lines | No | Number of lines to return (default: 100, max: 1000) | |
| tail | No | If true, return last N lines; if false, return first N lines (default: true) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes a read operation (returns log file content) with no side effects mentioned. However, it does not explicitly state read-only behavior, authentication needs, or potential limitations like missing logs. The description is adequate but not highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The first sentence states the tool's purpose, and the second adds key parameter details. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (4 optional parameters, no output schema), the description adequately covers functionality. It mentions auto-detection, launcher options, instance support, and tail behavior. Could specify return format or error cases, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter is already documented. The description adds value by explaining auto-detection behavior, that instance is only for Prism, and that line count is configurable with tail option. This enriches understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get Minecraft instance logs' which is a specific verb+resource. It distinguishes from sibling tools that are wiki or spyglass related, and provides additional context about auto-detection and launcher options.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving Minecraft instance logs but does not explicitly state when to use this tool versus alternatives. It provides guidance on parameter choices (auto-detect vs specify launcher) but lacks exclusion criteria or when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_wiki_categoryA
List all pages in a Minecraft Wiki category (e.g. 'Blocks', 'Items', 'Mobs', 'Commands').
| Name | Required | Description | Default |
|---|---|---|---|
| category | Yes | Category name (e.g., 'Blocks', 'Items', 'Mobs', 'Commands') | |
| limit | No | Max results (default 50) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must fully convey behavior. It fails to disclose whether the tool is read-only, how it handles missing categories, or if there is pagination beyond the limit parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and resource, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output schema and does not describe return format (e.g., page titles), which is needed for completeness. However, for a simple listing tool it is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds category examples and restates default limit, but does not significantly enhance parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'List' and resource 'pages in a Minecraft Wiki category', with concrete examples distinguishing from sibling search/retrieve tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Examples suggest appropriate usage (listing all pages in a known category), but no explicit when-to-use or when-not-to-use guidance versus alternatives like search_wiki.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_wiki_command_infoB
Get detailed syntax documentation for a specific Minecraft command from the wiki (arguments, permissions, examples).
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | Command name |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It mentions only that the tool gets documentation, but does not describe safety (e.g., read-only), permissions, rate limits, or what happens if the command is invalid. The agent learns the purpose but not the operational guardrails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that efficiently conveys purpose and scope. It avoids fluff but could optionally be structured with bullet points for readability. High information density with minimal words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup tool with one parameter and no output schema, the description is adequate but incomplete. It omits return format (e.g., plain text, structured), error handling, and whether the response includes cross-references. The agent has basic understanding but missing details for robust invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a property description for 'command' ('Command name'). The description adds no extra meaning beyond the schema; it merely restates that the tool targets a specific command. Baseline of 3 is appropriate as the schema already documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Get', the resource 'detailed syntax documentation', scope 'for a specific Minecraft command', and source 'from the wiki'. It clearly distinguishes from sibling tools like 'get_wiki_commands' (list) and 'get_wiki_page' (general page).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when command syntax details are needed but provides no explicit when-to-use, when-not-to-use, or alternatives. It lacks guidance like 'Use this instead of get_wiki_page for syntax-focused queries'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_wiki_commandsA
List all Minecraft commands from the wiki with their URLs. For detailed syntax of one command use get_wiki_command_info.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max commands to return (default 50) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It mentions that URLs are returned but does not disclose behavioral traits such as pagination, rate limits, or the effect of the limit parameter (default 50). The claim 'List all' may be inconsistent with the limit parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no waste. The first sentence states the core purpose, and the second provides a clear pointer to a sibling tool for more detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one optional parameter and no output schema, the description is fairly complete. It covers the primary action and directs to a sibling for details. However, it could mention that the output includes a list of command names and URLs, which is implied but not explicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the limit parameter. The description adds no additional meaning beyond clarifying that it lists commands from the wiki; it does not explain how the limit parameter behaves or its default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all Minecraft commands from the wiki with their URLs, and distinguishes itself from the sibling tool get_wiki_command_info which provides detailed syntax.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions an alternative for detailed syntax (get_wiki_command_info), providing clear guidance on when to use that tool instead. However, it does not explicitly state when not to use this tool or compare it to other list tools like spyglass_get_commands.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_wiki_pageA
Get a short summary and section list of a Minecraft Wiki page. For full content use get_wiki_page_content instead.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Page title (e.g., 'Creeper', 'Diamond Sword', 'Commands/execute') | |
| sentences | No | Number of sentences for summary (default 5) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the tool returns a short summary and section list, which is sufficient for a simple read operation. However, it does not elaborate on any potential limitations or behaviors beyond the return type.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences. The first sentence states the purpose, and the second provides usage guidance. No unnecessary words or details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no output schema, two parameters with clear schema, no nested objects), the description is complete. It covers the return type and suggests an alternative for extended needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (title, sentences) already described in the schema. The description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a short summary and section list of a Minecraft Wiki page, with a specific verb and resource. It distinguishes from the sibling tool 'get_wiki_page_content' by noting that the latter provides full content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs when to use this tool (for short summary) and when not (for full content), and names the alternative tool 'get_wiki_page_content'. This provides clear guidance for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_wiki_page_contentA
Get the full structured content of a Minecraft Wiki page (all sections, text, tables). Use get_wiki_page for a quick summary instead.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Page title |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states it returns full structured content with sections, text, tables, but lacks details on potential behavioral aspects like rate limits, authorization, or response size. Adequate for a simple read tool but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that efficiently conveys purpose and usage alternative. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, no output schema, and no annotations, the description covers purpose and alternative usage. However, it could elaborate on what 'full structured content' entails, but for a simple tool it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter 'title' described as 'Page title'. Description adds context about retrieving full content but does not add extra meaning beyond schema, such as format or case sensitivity. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get', resource 'full structured content of a Minecraft Wiki page', and specifies scope 'all sections, text, tables'. It also distinguishes from sibling by noting that get_wiki_page is for a quick summary instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool vs alternative: 'Use get_wiki_page for a quick summary instead.' Provides clear context but does not include when not to use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
misode_get_generatorsA
List all available datapack generators from Misode (loot tables, recipes, worldgen, advancements, etc.) with their URLs.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Filter by category |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates the tool lists generators with URLs, which is a simple read operation. However, it does not disclose any additional behavioral traits such as rate limits, data freshness, or whether the list is exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that immediately conveys the purpose and output. No redundant information, and it is front-loaded with the key action 'List all available datapack generators'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity and the presence of a schema that covers the only parameter, the description adequately explains the return value (list with URLs). It is mostly complete, though it could mention that the listing can be filtered by category.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for the 'category' parameter is 100%, with description and enum values. The tool description does not mention the parameter or add any additional meaning beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all available datapack generators from Misode, with specific examples (loot tables, recipes, etc.) and includes URLs. It distinguishes itself from sibling tools like misode_get_loot_tables and misode_get_recipes, which focus on specific generators.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for getting a general list of generators, but it does not explicitly guide when to use this versus more specific tools like misode_get_loot_tables or misode_get_recipes. No when-not-to-use or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
misode_get_loot_tablesA
List vanilla loot table IDs by category (blocks, chests, entities, archaeology, gameplay). Includes per-category counts.
| Name | Required | Description | Default |
|---|---|---|---|
| version | Yes | Minecraft version | |
| category | No | Filter by category | |
| search | No | Optional search query |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must carry behavioral info. It implies a read-only operation by saying 'list' and includes behavioral detail (includes counts). However, it does not disclose potential side effects, authentication needs, or rate limits. The description is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys the tool's purpose and key behavior. Every word adds value, and it is front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema, the description provides the essential information (listing IDs by category, including counts). However, it could be more specific about return format (e.g., JSON list with IDs and counts). Still, given the tool's straightforward nature, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but schema descriptions are generic ('Minecraft version', 'Filter by category', 'Optional search query'). The description enriches the category parameter by listing the specific enum values (blocks, chests, entities, archaeology, gameplay) and adds contextual behavior (includes counts). This adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool lists vanilla loot table IDs by specific categories and includes per-category counts. It clearly identifies the resource (loot tables) and the action (list), distinguishing it from sibling tools like misode_get_recipes or misode_get_generators.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or not use this tool. The context from sibling tools implies it is for loot table queries, but there is no mention of alternatives or constraints (e.g., only works for vanilla data).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
misode_get_preset_dataA
Get the full vanilla JSON for a specific preset. Use misode_get_presets first to discover available preset IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| version | Yes | Minecraft version | |
| generator_type | Yes | Generator type | |
| preset_id | Yes | Preset ID (e.g., 'chests/abandoned_mineshaft', 'diamond_sword') |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully convey behavior. It implies a read-only operation ('Get') but does not explain the output format (raw JSON), error handling, or any side effects. Adequate but could be more informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose, second provides crucial usage hint. No unnecessary words, front-loaded information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 required parameters, no output schema, and no annotations, the description could elaborate on the return value (e.g., 'returns a JSON string') or error conditions. It suffices but lacks completeness for a production tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions already present. The tool description adds no additional meaning beyond the schema, just a usage hint. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('full vanilla JSON for a specific preset'), distinguishing it from the sibling tool 'misode_get_presets' which discovers IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends using 'misode_get_presets first to discover available preset IDs', guiding the agent on the correct workflow. Lacks explicit when-not-to-use statements but provides strong positive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
misode_get_presetsA
List vanilla preset IDs for a generator type (e.g. 'loot_table', 'recipe', 'worldgen/biome'). Use search to filter. Get full JSON with misode_get_preset_data.
| Name | Required | Description | Default |
|---|---|---|---|
| version | Yes | Minecraft version (e.g., '1.21.4') | |
| generator_type | Yes | Generator type (e.g., 'loot_table', 'recipe', 'worldgen/biome', 'advancement') | |
| search | No | Optional search query to filter presets |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It describes a read operation listing IDs without side effects, but lacks details on pagination, rate limits, or output format. Adequate for a simple listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no waste. Front-loaded with purpose, then usage hint, then sibling reference. Excessively efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 3 simple parameters, the description is mostly complete: it states what is returned (IDs), how to filter, and cross-references the sibling. Missing details on output format but sufficient for an agent to use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds marginal value by reinforcing generator_type examples and stating search filters. Baseline 3 is appropriate as the schema already explains parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists vanilla preset IDs for a generator type, with concrete examples. It distinguishes from sibling misode_get_preset_data by noting that this tool returns IDs while the sibling gets full JSON.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains to use search to filter and mentions the sibling for full JSON, providing clear context for when to use this tool versus alternatives. No explicit when-not-to-use instructions, but sufficient for typical usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
misode_get_recipesA
List vanilla recipe IDs with optional filtering by type (crafting_shaped, smelting, stonecutting, etc.) and search query.
| Name | Required | Description | Default |
|---|---|---|---|
| version | Yes | Minecraft version | |
| recipe_type | No | Filter by recipe type | |
| search | No | Optional search query |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states the tool 'lists' data, implying read-only behavior, and mentions filtering, which adds some context. However, it does not disclose response format, pagination, error conditions, or any constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that immediately states the verb and resource, then conditionally adds filtering details. No wasted words, front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with three parameters and no output schema, the description covers the basic functionality and filtering options. It is not completely thorough (e.g., missing return format), but is sufficient given tool complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description only adds minimal context (e.g., 'vanilla recipe IDs', examples of recipe types). The schema already describes each parameter, so the description adds little beyond baseline value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists vanilla recipe IDs with optional filtering by type and search query. The verb 'List' and resource 'vanilla recipe IDs' are specific, and the filtering options distinguish it from sibling tools like get_logs or get_wiki_category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool vs. alternatives. It does not mention when not to use it or suggest other tools for related tasks, leaving the agent to infer based solely on the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
misode_list_versionsA
List all Minecraft versions available in the Misode API for datapack data lookups.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool lists all versions but does not disclose any behavioral traits such as pagination, rate limits, or the format of returned data. Adequate but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that clearly communicates the purpose without any redundant information. It is concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description is adequate but minimal. It does not explain the return structure (e.g., what information is provided per version), which could help the agent process the results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to explain parameter semantics. Baseline of 4 is appropriate as there is no parameter information to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'List' and the resource 'all Minecraft versions available in the Misode API for datapack data lookups'. It is specific about the scope (Minecraft versions, Misode API, datapack data) and distinguishes this tool from siblings like 'spyglass_get_versions'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving Minecraft versions for datapack lookups, but it does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_mojiraA
Search the Mojira bug tracker. Returns issue key, URL, summary, status, reporter, assignee, and creation date. Filter by project (MC, MCPE, etc.), status, or resolution.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search text (minimum 3 characters) | |
| project | No | Filter by project | |
| status | No | Filter by status | |
| resolution | No | Filter by resolution | |
| page | No | Page number (default 1) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses return fields but does not mention behavioral details such as case sensitivity, pagination behavior (page parameter is in schema but no explanation of results per page), authentication, or rate limits. Adequate but with gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence front-loads the purpose and return fields, the second adds filter options. Highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers the essential aspects: what it does, what it returns, and filter options. Missing details like default page size or result set limits, but for a search tool it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds minimal value beyond the schema: it mentions filtering by project, status, resolution but does not explain the query parameter's format beyond what the schema already provides (minimum 3 characters). No extra semantics for page or enum values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches the Mojira bug tracker and lists the returned fields (issue key, URL, summary, status, reporter, assignee, creation date). It specifically names the resource (Mojira bug tracker) and the action (search), distinguishing it from sibling tools like search_wiki which search a wiki.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions filter options (project, status, resolution) but does not explicitly state when to use this tool versus alternatives like search_wiki. However, the context of bug tracker vs wiki is implied. It provides clear context but lacks explicit exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_wikiA
Search Minecraft Wiki for pages matching a query. Use fulltext=true for snippet-based search. Returns titles, URLs, and optional snippets.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query | |
| limit | No | Max results (default 10) | |
| fulltext | No | Use full-text search with snippets (default false) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses return fields (titles, URLs, optional snippets) but lacks information about authentication, rate limits, or query syntax. Since no annotations are provided, the description adds value by describing the output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description mentions return fields. It does not cover error handling or edge cases, but is reasonably complete for a simple search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the effect of fulltext=true, which is beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search') and the specific resource ('Minecraft Wiki pages'), and distinguishes from sibling tools like get_wiki_page by mentioning query-based search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear usage hint for the fulltext parameter ('Use fulltext=true for snippet-based search'), but does not explicitly state when this tool should be preferred over other wiki tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
spyglass_get_block_statesA
Get all block state properties (e.g. facing, waterlogged, power) and their default values for a specific block ID.
| Name | Required | Description | Default |
|---|---|---|---|
| version | Yes | Minecraft version | |
| block_id | Yes | Block ID (e.g., 'oak_stairs', 'minecraft:redstone_wire') |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behavioral traits. The verb 'Get' implies a read-only operation, which is transparent. However, it does not explicitly state that the tool is non-destructive or any other limitations, but the intent is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is concise, well-structured, and includes relevant examples without any fluff. Every word contributes to the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description hints at the output (list of properties with default values) but does not specify the format. For a simple tool, this is adequate, and the context from sibling tools is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters (100% coverage). The description adds value by providing concrete examples for block_id (e.g., 'oak_stairs') and property examples, thereby enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action (Get), the resource (block state properties and default values), and provides examples (facing, waterlogged, power). It distinguishes from sibling tools like spyglass_get_commands or spyglass_get_registries by focusing on block states.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly states when to use (when you need block state properties for a block ID) but does not provide explicit guidance on when not to use or alternatives among sibling tools. It lacks explicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
spyglass_get_commandsA
Get the full command tree/syntax for a Minecraft version. Optionally pass a command name to get its specific argument tree.
| Name | Required | Description | Default |
|---|---|---|---|
| version | Yes | Minecraft version | |
| command | No | Optional specific command name to get details for |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It states a read-like operation (get), but lacks details on side effects, rate limits, or permissions. Adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences with no filler. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should hint at return format. It doesn't. For a medium-complexity tool with many siblings, it's adequate but could explain that it returns JSON or tree structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. Description adds value by explaining the optional command parameter yields its 'specific argument tree', enhancing meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Get' and the resource 'full command tree/syntax for a Minecraft version', with an optional specificity for a command name. This differentiates from sibling tools like get_wiki_commands which focus on wiki content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for retrieving command tree data, but no explicit when-to-use vs alternatives (e.g., get_wiki_commands) or exclusions. Provides no context about when to provide a command name vs not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
spyglass_get_mcdoc_symbolsA
Get vanilla mcdoc type symbols from Spyglass. Useful for understanding NBT/datapack data structures.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the tool retrieves symbols from Spyglass, but does not mention any side effects, authentication, rate limits, or output format. For a simple read tool, this is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, followed by context. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (no parameters, no output schema). The description covers what it does and why it's useful. It is complete enough for an agent to understand its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, meeting the baseline of 4 per guidelines. The description does not need to add parameter information since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get' and the resource 'vanilla mcdoc type symbols from Spyglass', with a clear purpose of understanding NBT/datapack data structures. It distinguishes itself from sibling spyglass tools (e.g., spyglass_get_block_states) by specifying 'mcdoc' symbols.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use it ('for understanding NBT/datapack data structures'), but no explicit when-not-to-use or alternatives. However, given sibling tool names, an agent can infer this is for mcdoc symbols specifically.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
spyglass_get_registriesB
Get registry entries for a Minecraft version. Supports item, block, entity_type, biome, enchantment, and many more. Use the optional search param to filter results.
| Name | Required | Description | Default |
|---|---|---|---|
| version | Yes | Minecraft version (e.g., '1.21', '1.20.4') | |
| registry | Yes | Registry name (e.g., 'item', 'block', 'entity_type', 'biome', 'enchantment') | |
| search | No | Optional search query to filter results |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behaviors. It mentions optional search but fails to state whether the tool is read-only, requires authentication, or has pagination. Important behavioral traits like data freshness or rate limits are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely conciseβtwo sentences with no fluff. The first sentence states the primary action, and the second adds supporting context. Every word contributes meaning, making it efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters) and lack of output schema, the description provides basic operational info but misses details like return format or pagination. It is adequate for simple invocation but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter is already well-described. The description adds examples for the registry parameter, but these largely repeat the schema's examples. The mention of 'many more' and the search param note add minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get registry entries for a Minecraft version.' It lists supported registries like item, block, entity_type, etc., making the resource specific. The verb 'Get' and the resource 'registry entries' are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. While the sibling tools include other 'get' tools like spyglass_get_block_states, the description does not differentiate usage contexts. The agent receives no hints about when to choose this over other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
spyglass_get_versionsA
List Minecraft Java Edition versions with their data/resource pack versions. Filter by release or snapshot. Includes latest release & snapshot info.
| Name | Required | Description | Default |
|---|---|---|---|
| type_filter | No | Filter by version type | |
| limit | No | Max versions to return (default 20) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses that it includes latest release & snapshot info and has a default limit of 20. It does not discuss ordering or pagination, but for a read-only list tool, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and contains no extraneous information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not detail return format, but it explains filtering and inclusion of latest versions. For a simple, list-type tool, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters with descriptions, and the tool description adds minimal extra meaning (e.g., 'default 20' for limit). With 100% schema coverage, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists Minecraft Java Edition versions with associated data/resource pack versions, and specifies filtering by release or snapshot. This distinguishes it from sibling tools like spyglass_get_commands.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions filtering options (release/snapshot) and default limit, guiding the agent on parameter use. However, it does not explicitly state when to use this tool over alternatives like misode_list_versions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
Tools are clearly grouped by prefix (get_logs, get_wiki, misode, search, spyglass) and each has a distinct purpose. Cross-references in descriptions prevent confusion between similar tools like get_wiki_page and get_wiki_page_content.
All tool names follow a consistent verb_noun pattern with snake_case and server-specific prefixes. The naming is predictable across all 19 tools, e.g., misode_get_generators, spyglass_get_versions.
With 19 tools, the set is slightly above the ideal 3-15 range but remains well-scoped for a Minecraft helper server covering logs, wiki, datapack generation, bug tracking, and game data.
The tool surface covers major Minecraft domains (logs, wiki, datapacks, bugs, game data) with reasonable depth. Minor gaps exist (e.g., no world editing or mod management) but are not central to the server's purpose.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
An MCP server that gives your AI access to the source code and docs of all public github repos
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
An MCP server that integrates with Discord to provide AI-powered features.
Related MCP Servers
- AlicenseBqualityCmaintenanceAn MCP server that supercharges AI assistants with powerful tools for software development, enabling research, planning, code generation, and project scaffolding through natural language interaction.1167101MIT
- AlicenseNot gradedqualityBmaintenanceA local MCP server that provides AI coding assistants with semantic search capabilities over codebases. It indexes code using local embeddings and exposes tools for efficient code retrieval, saving tokens and improving response quality.314MIT
- AlicenseNot gradedqualityAmaintenanceA Model Context Protocol server that gives AI assistants native access to Minecraft mod development tools β decompile, remap, search, and analyze Minecraft source code directly from your AI workflow.8535MIT
- AlicenseNot gradedqualityAmaintenanceProvides a local MCP server for searching and retrieving documentation from 22+ open-source projects, enabling AI coding assistants to access up-to-date docs without network dependency.112MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/AnCarsenat/minecode-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server