Skip to main content
Glama
Sign In
krejcif

Magector

by krejcif
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

Magector

MCP server for Magento 2 and Adobe Commerce: a semantic index of the codebase plus structural tools that read the Magento configuration.

Magector is a Model Context Protocol (MCP) server for Magento 2 and Adobe Commerce codebases. It builds a semantic vector index of the project's PHP, XML, JS, PHTML and GraphQL files (and the module READMEs under app/code) and exposes 48 tools that AI assistants use to search and navigate the code. A query such as "how are checkout totals calculated?" returns ranked files, each annotated with the Magento component type detected for it (plugin, observer, controller, block, layout XML and others). Structural tools answer questions such as "which plugins intercept this method" from di.xml, events.xml, webapi.xml and the other configuration files, without the vector index.

Node.js Magento License: MIT

Why Magector

A Magento 2 or Adobe Commerce project consists of PHP, XML, JS, PHTML and GraphQL files spread across hundreds of modules. The codebase relies heavily on indirection: plugins intercept methods defined in other modules, observers react to events dispatched elsewhere, di.xml rewires interfaces to concrete classes, and layout XML stitches blocks and templates together.

Magector provides two kinds of answers:

  1. Semantic vector index — every indexed file is embedded into a 384-dimensional space with the ONNX model bge-small-en-v1.5, and a query is matched to the nearest vectors (combined with keyword reranking), not to literal strings.

  2. Magento pattern detection — the indexer classifies files by path and by their PHP AST (controllers, plugins, observers, blocks, models, repositories, GraphQL resolvers, cron, setup patches, API interfaces, configuration XML types and more). Every search result carries that classification.

The structural tools (DI, events, Web API, GraphQL, cron, DB schema and others) read the configuration files directly; see How exact are the results?.

Related MCP server: Axon.MCP.Server

Features

  • Semantic search -- natural-language queries matched against embedding vectors of the indexed files

  • Hybrid search -- combines semantic vector similarity with keyword re-ranking

  • Structured JSON output -- semantic results include file path, class name, methods list, role badges and, for the top results, a content snippet

  • Persistent serve mode -- a long-running magector-core serve process keeps the ONNX model and the vector index in memory, so a query does not load them

  • Incremental re-indexing -- a background file watcher re-indexes changed files without a restart (tombstone + compact strategy)

  • ONNX embeddings -- 384-dim embeddings with bge-small-en-v1.5 via ONNX Runtime (CPU)

  • Magento-aware -- path- and AST-based detection of controllers, plugins, observers, blocks, resolvers, repositories and other Magento file types

  • Adobe Commerce -- Adobe Commerce modules are indexed and parsed like Open Source modules (the verification runs in this repo used Magento Open Source and Mage-OS)

  • AST-based -- tree-sitter parsing for PHP and JavaScript extracts classes, methods, namespaces and inheritance

  • Cross-tool hints -- tool descriptions include keywords and "See also" references to related tools

  • SONA feedback learning -- learns from MCP tool call sequences (e.g. search → find_plugin) and boosts matching result types for similar queries; an evaluation found no measurable ranking change. A rank-2 MicroLoRA adapter (1536 parameters) with EWC regularisation is present in the code but is not trained online (see SONA Feedback Learning)

  • Diff analysis -- risk scoring and change classification for a git commit or the staged changes

  • Complexity analysis -- cyclomatic complexity, function count and line count per file

  • LLM description enrichment -- optional natural-language descriptions of di.xml files generated with Claude, stored in SQLite and prepended to the embedding text so they influence vector ranking

  • MCP server -- 48 tools for Claude Code, Cursor and other MCP clients

  • Split architecture -- the Rust core does indexing, embedding and vector search; the Node.js layer provides the CLI and the MCP server

Architecture

flowchart LR
  subgraph node ["Node.js Layer"]
    direction TB
    G["CLI<br/>init · index · search · describe · snapshot"]
    E["MCP Server<br/>48 tools · query cache"]
    F["Persistent Serve Process"]
    E --> F
  end

  G -->|"one-shot commands"| rust
  F -->|"stdin/stdout JSON"| rust

  subgraph rust ["Rust Core"]
    direction TB
    A["AST Parser<br/>PHP · JS (tree-sitter)"]
    B["Pattern Detection<br/>path + AST rules"]
    B2["Description Enrichment<br/>LLM di.xml summaries (optional)"]
    C["ONNX Embedder<br/>bge-small-en-v1.5 · 384d"]
    D["Vector Search<br/>exact ≤300k · HNSW above · hybrid rerank · SONA"]
    A --> B --> B2 --> C --> D
  end

  style rust fill:#f4a460,color:#000
  style node fill:#68b684,color:#000

Indexing Pipeline

flowchart LR
  A["Source File"] --> B["AST Parser"]
  B --> C["Pattern Detection"]
  C --> D["Text Enrichment"]
  D --> D2{"Descriptions DB?"}
  D2 -->|Yes| D3["Prepend LLM Description"]
  D2 -->|No| E["ONNX Embedding"]
  D3 --> E
  E --> F[("Vector Index<br/>index.db")]
  A --> G["Metadata"] --> F

Search Pipeline

flowchart LR
  Q["Query"] --> E1["Synonym Expansion<br/>(MCP server)"]
  E1 --> E2["ONNX Embedding"]
  E2 --> H["Vector Search"]
  H --> R["Hybrid Reranking"]
  R --> SA["SONA Adjustment"]
  SA --> J["Structured JSON"]

Components

Component

Technology

Purpose

Embeddings

ort (ONNX Runtime, CPU)

bge-small-en-v1.5, 384 dimensions

Vector search

exact cosine scan up to 300k vectors, hnsw_rs above + hybrid reranking

Nearest neighbors + keyword boosting

PHP parsing

tree-sitter-php

Class, method, namespace extraction

JS parsing

tree-sitter-javascript

AMD/ES6 module detection

Pattern detection

Custom Rust

Magento file types from path and AST

CLI

clap

Rust command-line interface (index, search, serve, describe, validate, download, stats, embed)

Metadata

rusqlite (bundled SQLite)

.magector/data.db: method-chain enrichment, process state, cache. .magector/sqlite.db: LLM descriptions of di.xml files

SONA

Custom Rust

Feedback learning from tool call sequences (pattern boosts; the MicroLoRA + EWC++ code path is not trained online)

MCP server

@modelcontextprotocol/sdk

AI tool integration

Config data

JSON exports in .magector/config-data/

One-time core_config_data exports per environment for config tracing

PHP scan snapshot

JSON in .magector/php-scan.json (0600)

Class hierarchy and event dispatch sites read once per root and shared by its MCP instances, checked by file stamps

Security

Magector operates on source code indexed from potentially untrusted vendor/ dependencies and is driven by an LLM that may be manipulated via prompt injection in indexed comments, docblocks or markdown. The following hardening applies:

Indexed markdown

The only markdown in the index is the project's own module READMEs, app/code/<Vendor>/<Module>/README.md: written next to that code and trusted like its comments. Markdown from vendor/ packages and anywhere else is never indexed, so magento_search does not hand third-party markdown to the LLM. Code in vendor/ is indexed, so its comments and docblocks are in the index and can appear in result snippets.

Path arguments

Tools that read files under a path argument route it through the safePath() / safeRelPath() helpers in src/mcp-server.js:

  • safePath(): magento_read (also inside magento_batch) and magento_complexity

  • safeRelPath(): magento_grep, magento_ast_search and magento_find_dataobject_issues (also inside magento_batch), and magento_validate_config

These helpers:

  1. Resolve the argument against MAGENTO_ROOT with path.resolve(), which normalizes ...

  2. Reject any resolved path that does not lie inside MAGENTO_ROOT.

This stops a hostile vendor/ comment from instructing the LLM to e.g. magento_read ../../home/user/.ssh/id_rsa. The check is lexical: symlinks are not resolved, so a symlink inside MAGENTO_ROOT that points outside it passes the check and its target is read.

Other path-related rules:

  • magento_complexity also rejects a module that is not of the form Vendor_Module.

  • magento_index is not confined to MAGENTO_ROOT: its path is resolved against the server's working directory and must be an existing directory; anything else is refused. The index is written to the configured MAGECTOR_DB, replacing the current project's index.

The confinement only stops reads outside MAGENTO_ROOT. Everything inside it is readable by magento_read and magento_grep, including app/etc/env.php (database password, crypt key). Do not run the server against a root that holds production secrets.

Git refs in magento_analyze_diff

commitHash must be a plain git ref: it starts with a letter or digit, contains only letters, digits and _ . / ^ ~ -, optionally ends in a reflog selector @{n}, and contains no ... Anything else is rejected. git runs without a shell, as git -C $MAGENTO_ROOT … with an argument array. An unknown ref, or a root that is not a git repository, returns git's error instead of an empty result.

Auto-update

src/update.js reads the version of the latest dist-tag from https://registry.npmjs.org/magector/latest (cached for 1 h in .magector/version-check.json when the current directory has .magector/, else in ~/.magector/version-check.json) and re-runs the CLI with that version when it is newer:

  • A semver-strict isSafeVersion() validator rejects any version string that does not match X.Y.Z / X.Y.Z-prerelease.

  • On POSIX the re-exec passes argv as an array with no shell.

  • On Windows, where npx is a .cmd shim, the re-exec needs a shell; every argument is first checked against an allow-list, and the update is skipped (the current version runs) when an argument contains characters cmd.exe would interpret (spaces, &, |, quotes).

  • Fails closed: when the version or an argument is rejected, the update is skipped.

  • It never runs for mcp or help, and not when MAGECTOR_NO_UPDATE is set. The MCP config written by init starts the server as npx -y magector@latest mcp, so each MCP start can still fetch a newer version; pin magector@<version> in .mcp.json / ~/.cursor/mcp.json to keep one version.

Unix socket permissions

The serve-proxy Unix socket at .magector/serve.sock is set to mode 0600 right after listen(), so other local accounts cannot connect and query the index (which would leak indexed source snippets). If the chmod fails (e.g. on a platform without it), a warning is logged to .magector/magector.log.

Reporting vulnerabilities

Report security issues privately through GitHub's private vulnerability reporting (the repository's Security tab → Report a vulnerability), not in a public issue. Do not include reproducers that leak source contents from private codebases.

Quick Start

Prerequisites

1. Initialize in Your Project

cd /path/to/your/magento2  # or Adobe Commerce project
npx magector init

This command handles the setup:

flowchart LR
  A["npx magector init"] --> B["Verify<br/>Project"]
  B --> B2["Resolve<br/>Binary"]
  B2 --> C["Prepare<br/>Model Dir"]
  C --> D["Index<br/>Codebase"]
  D --> E["Detect IDE<br/>Cursor · Claude Code"]
  E --> E2["API Key<br/>(optional)"]
  E2 --> F["Write MCP<br/>Config"]
  F --> R["Write IDE Rules<br/>CLAUDE.md · Cursor"]
  R --> G["Update<br/>.gitignore"]

2. Search

npx magector search "product price calculation"
npx magector search "checkout totals collector" -l 20

3. Re-index After Changes

npx magector index

4. IDE Setup Only (Skip Indexing)

npx magector setup

Manual MCP configuration

For another MCP client, or to write the config by hand, use the entry init writes (.mcp.json for Claude Code, ~/.cursor/mcp.json for Cursor):

{
  "mcpServers": {
    "magector": {
      "command": "npx",
      "args": ["-y", "magector@<version>", "mcp"],
      "env": {
        "MAGENTO_ROOT": "/path/to/magento",
        "MAGECTOR_DB": "/path/to/magento/.magector/index.db"
      }
    }
  }
}

init writes magector@latest; a pinned version is shown here. init adds MAGECTOR_MODELS (absolute) when it is set, and ANTHROPIC_API_KEY when you enter a key.

CLI Reference

Rust Core CLI

magector-core [-v|--verbose] <COMMAND>

Commands:
  index       Index a Magento codebase
  search      Search the index semantically
  serve       Start persistent server mode (stdin/stdout JSON protocol)
  describe    Generate LLM descriptions for di.xml files (requires an Anthropic API key)
  validate    Run the validation suite (downloads Magento if no root is given)
  download    Download Magento 2 Open Source
  stats       Show index statistics
  embed       Generate embedding for text

-v, --verbose is a global flag.

index

magector-core index -m <PATH> [OPTIONS]

Options:
  -m, --magento-root <PATH>          Path to Magento root directory (required)
  -d, --database <PATH>              Index database path [default: ./.magector/index.db]
  -c, --model-cache <PATH>           Model cache directory [default: ./models]
      --descriptions-db <PATH>       Path to descriptions SQLite DB (descriptions are prepended to embeddings)
      --threads <N>                  Max ONNX + rayon threads [default: half of CPU cores for ONNX; also MAGECTOR_THREADS]
      --batch-size <N>               Embedding batch size [default: 256; also MAGECTOR_BATCH_SIZE]
      --force                        Discard any existing index and rebuild (without it, indexing resumes)

When --descriptions-db is provided (or auto-detected as sqlite.db next to the index), descriptions are prepended to the embedding text as "Description: {text}\n\n" before the raw file content. This places the description within the 256 tokens the embedding model reads.

search

magector-core search <QUERY> [OPTIONS]

Options:
  -d, --database <PATH>      Index database path [default: ./.magector/index.db]
  -c, --model-cache <PATH>   Model cache directory [default: ./models]
  -l, --limit <N>            Number of results [default: 10]
  -f, --format <FORMAT>      Output format: text, json [default: text]

describe

magector-core describe -m <PATH> [OPTIONS]

Options:
  -m, --magento-root <PATH>   Path to Magento root directory (required)
  -o, --output <PATH>         Output SQLite database [default: ./.magector/sqlite.db]
      --api-key <KEY>         Anthropic API key [default: $ANTHROPIC_API_KEY]
      --model <MODEL>         Model [default: claude-sonnet-4-5-20250929]
      --force                 Re-describe all files (ignore cache)

Generates natural-language descriptions of di.xml files using the Anthropic API. Descriptions are stored in a SQLite database and used during indexing to enrich embeddings. Only files with changed content hashes are re-described (incremental by default).

serve

magector-core serve [OPTIONS]

Options:
  -d, --database <PATH>            Index database path [default: ./.magector/index.db]
  -c, --model-cache <PATH>         Model cache directory [default: ./models]
  -m, --magento-root <PATH>        Magento root (enables file watcher)
      --descriptions-db <PATH>     Path to descriptions SQLite DB
      --watch-interval <SECS>      File watcher poll interval [default: 60]
      --threads <N>                Max ONNX threads [default: half of CPU cores]

Starts a persistent process that reads JSON requests from stdin and writes JSON responses to stdout. It keeps the ONNX model and the vector index in memory for repeated queries.

When --magento-root is provided, a background file watcher polls for changed files every --watch-interval seconds and re-indexes them without a restart. The MCP server starts serve with --watch-interval set to MAGECTOR_WATCH_INTERVAL (default 300 s). Vectors of modified and deleted files are soft-deleted (tombstoned); new vectors are appended. When more than 20% of the vectors are tombstoned, they are purged (and the HNSW graph, used only above 300k vectors, is rebuilt).

Protocol (one JSON object per line):

On start, serve prints a ready line: {"ok":true,"ready":true,"vectors":N,"watcher":true|false}. Every reply is one JSON object; errors are {"ok":false,"error":"..."}. A request may carry an id field; the reply then carries the same id, copied verbatim. A reply that would not be valid JSON is replaced by {"ok":false,"error":"serve produced invalid JSON: …"}.

// Request:
{"command":"search","query":"product price","limit":10}

// Response:
{"ok":true,"data":[{"id":123,"score":0.85,"metadata":{...}}]}

// Stats request:
{"command":"stats"}

// Watcher status:
{"command":"watcher_status"}
// Response:
{"ok":true,"data":{"running":true,"tracked_files":18234,"last_scan_changes":3,"interval_secs":60}}

// Descriptions (all LLM descriptions from SQLite DB):
{"command":"descriptions"}
// Response:
{"ok":true,"data":{"app/code/Magento/Catalog/etc/di.xml":{"hash":"...","description":"...","model":"claude-sonnet-4-5-20250929","timestamp":1769875137},...}}

// Describe (generate descriptions + re-index the described files):
{"command":"describe","magento_root":"/var/www/html","force":false}
// Response:
{"ok":true,"data":{"total_files":371,"generated":5,"skipped":366,"errors":0}}

// SONA feedback (pattern learning only; no embedding update):
{"command":"feedback","signals":[{"type":"refinement_to_plugin","query":"checkout totals","timestamp":1700000000000}]}
// Response:
{"ok":true,"data":{"learned":1}}

// SONA status:
{"command":"sona_status"}
// Response:
{"ok":true,"data":{"learned_patterns":5,"total_observations":12,"term_patterns":3,"global_observations":12}}

Required fields: query for search, magento_root for describe (optional: output, force, api_key, model), signals for feedback; limit defaults to 10. Feedback signals may also carry searchResultPaths, followedTool, followedArgs, originalQuery and refinedQuery. The values in the examples are illustrative.

The MCP server also uses these internal commands: enrich and enrich_query (method-chain index), ast_query (tree-sitter patterns), grep, process_set / process_get / process_remove and cache_set / cache_get (process state and cache in data.db).

validate, download, stats, embed

magector-core validate [-m <PATH>] [-d <PATH>] [-c <PATH>] [-r <PATH>] [-s]
  # -m: Magento root (downloaded if absent); -d [./validation.db]; -c [./models];
  # -r, --report [./validation_report.json]; -s, --skip-index (reuse an existing index)
magector-core download [-t <PATH>] [--version <TAG>]
  # -t, --target [./magento2]; --version [2.4.7]
magector-core stats [-d <PATH>]
magector-core embed -t <TEXT> [-c <PATH>]

Node.js CLI

npx magector init [path] [--threads n] [--batch-size n] [--force]   # Full setup: index + IDE config
npx magector index [path]       # Index (or re-index) Magento codebase
npx magector search <query>     # Search indexed code
npx magector describe [path] [--force]   # Generate LLM descriptions for di.xml files
npx magector stats              # Show indexer statistics
npx magector setup [path]       # IDE setup only (no indexing)
npx magector snapshot save <file> [path]   # Index, then archive the index + PHP scan
npx magector snapshot load <file> [path]   # Restore an archive into a root
npx magector snapshot info <file>          # Version, root and entries of an archive
npx magector mcp                # Start MCP server
npx magector version            # Print the version (also --version, -V)
npx magector help               # Show help

Options: search -l, --limit <n> (default 10), -f, --format text|json; init and index --threads <n>, --batch-size <n>, --force; describe --force; snapshot save --no-index; snapshot load --update.

Put the path first when you pass both a path and options. init takes the first argument that does not start with - as the path, so init --threads 2 /path would use 2 as the path. describe takes the argument right after describe as the path: use npx magector describe . --force or npx magector describe /path/to/magento --force, not npx magector describe --force.

npx magector validate and npx magector benchmark (and the npm scripts validate, validate:verbose, validate:keep, benchmark) are currently broken: they fail with "Cannot find module …/src/indexer.js". Use magector-core validate instead.

init always writes the index to <path>/.magector/index.db (it ignores MAGECTOR_DB) and does not take the .magector/reindex.pid lock, so do not run it while another indexer is running on the same root.

The describe command and magento_describe MCP tool require an Anthropic API key. During npx magector init, you are prompted to paste your key (optional). If provided, it is stored in the MCP config file as the ANTHROPIC_API_KEY environment variable so the MCP server can use it. For Claude Code that file is <project>/.mcp.json, and init adds only .magector/ to .gitignore: keep .mcp.json out of git, or leave the key out and set ANTHROPIC_API_KEY in your environment or a user-level config instead. You can also set it later by adding "ANTHROPIC_API_KEY": "sk-..." to the env section in .mcp.json or ~/.cursor/mcp.json.

Environment Variables

Variable

Description

Default

MAGENTO_ROOT

Path to Magento installation

Current directory

MAGECTOR_DB

Path to index database

$MAGENTO_ROOT/.magector/index.db (index <path>: <path>/.magector/index.db)

MAGECTOR_BIN

Path to magector-core binary

Auto-detected

MAGECTOR_MODELS

Model directory; a missing model is downloaded here. Lookup order: MAGECTOR_MODELS (if it holds the model files), ~/.magector/models, then rust-core/models in a source checkout

~/.magector/models/

MAGECTOR_INDEX_TIMEOUT

Indexing wall-clock timeout in milliseconds. Override for very large codebases or CPU-constrained environments.

14400000 (4 h)

MAGECTOR_THREADS

Max ONNX intra-op + rayon parsing threads. Equivalent to the --threads CLI flag.

ONNX: half of CPU cores; parsing: all cores

OMP_NUM_THREADS

Fallback thread limit if MAGECTOR_THREADS is not set (de facto standard for ONNX/OpenMP).

—

MAGECTOR_BATCH_SIZE

Embedding batch size (higher = fewer inference calls, more RAM). Equivalent to --batch-size.

256

MAGECTOR_WATCH_INTERVAL

Seconds between file-watcher scans of the serve process started by the MCP server

300

MAGECTOR_NO_UPDATE

Any value: the CLI does not check npm for a newer version and does not re-run itself (images, CI)

—

MAGECTOR_MAX_OUTPUT_CHARS

Cap on one MCP tool answer, in characters; a longer answer is cut at a line boundary with a note to narrow the query.

40000

MAGECTOR_FILE_LIST_TTL_MS

How long the list of the modules' etc/ files is reused before it is listed again (files added mid-session show up after this); also how often composer's PSR-4 map and classmap are checked for a composer dump-autoload. Modules themselves are rediscovered as soon as app/etc/config.php or the composer registrations change. 0: always fresh.

2000

MAGECTOR_SERVE_WAIT_MS

How long a search waits for the serve process to become ready before it runs a single-shot search instead.

20000

MAGECTOR_SERVE_QUERY_TIMEOUT_MS

Time limit of one query that a secondary MCP instance sends to the primary's serve process over .magector/serve.sock; keep it above MAGECTOR_SERVE_WAIT_MS

MAGECTOR_SERVE_WAIT_MS + 10000

MAGECTOR_PHP_LIST_TTL_MS

How long the list of all PHP files (event dispatchers) is reused before the tree is walked again.

30000

MAGECTOR_AUTO_INDEX

0: the MCP server never starts an index (none, or an incompatible one) — for CI and agent jobs that bring their own index. The structural tools work without one; semantic search reports it is missing.

1 (index in the background)

MAGECTOR_PREWARM_PHP

1: read the PHP class hierarchy and the event dispatch sites in the background after the MCP server starts, in every instance, so the first find_event_dispatchers / find_implementors call does not read the tree; 0: never — their first call reads the tree (seconds on a large project). Unset: in the primary instance only (the one that owns the serve process), except with MAGECTOR_AUTO_INDEX=0, which keeps background CPU off.

primary instance (off with MAGECTOR_AUTO_INDEX=0)

MAGECTOR_PHP_SNAPSHOT

0: every MCP instance reads the PHP tree itself. Default: the instance that reads it writes .magector/php-scan.json; the other instances of the same root load it, checked against the tree by the mtime and size of every file it read, instead of reading the tree again.

on

MAGECTOR_PHP_SCAN_WAIT_MS

How long an instance waits for another instance's PHP scan (.magector/php-scan.lock) before it reads the tree itself.

180000

MAGECTOR_PREWARM_CONFIG

1: prepare the configuration notice of the DI / event answers (every di.xml / events.xml read, each area merged; 0.2–0.6 s on 300–600 modules) in the background, 1.5 s after the MCP server starts with no tool call in flight, so the first DI answer does not wait for it; 0: never — the first DI or event answer prepares it. 1 runs it in every instance. Unset: in the primary instance only, except with MAGECTOR_AUTO_INDEX=0, which keeps background CPU off. Only on a Magento install (app/etc/config.php under MAGENTO_ROOT).

primary instance (off with MAGECTOR_AUTO_INDEX=0)

MAGECTOR_PHP

Command that runs PHP 8.1+ able to load the Magento root, for the native magento_validate_config (the PHP program is piped to its stdin), e.g. docker exec -i -u www-data <container> php, warden env exec -T php-fpm php, ddev exec php. Only an explicit command is used — never php from PATH: the native check loads the project's autoloader and bootstraps Magento (which writes its DI config to the configured cache; with var/.regenerate present the areas are not read, as bootstrapping would delete generated/ and var/cache). Unset: built-in check.

—

MAGECTOR_PHP_TIMEOUT_MS

Time limit of one native check (it runs asynchronously; the server keeps answering).

120000

MAGECTOR_PHP_ROOT

The Magento root as MAGECTOR_PHP sees it (inside the container)

MAGENTO_ROOT

ANTHROPIC_API_KEY

API key for description generation (describe command)

—

These defaults apply to the Node.js CLI and the MCP server. The Rust core's own -d flag (see above) defaults to ./.magector/index.db in its working directory, and its -c flag to ./models.

Running in containers

The Linux binaries (x64 and arm64) link libstdc++ statically and need glibc 2.34 or newer: they run in Warden and DDEV PHP containers (CentOS Stream 9 / RHEL 9), Debian 12 and Ubuntu 22.04+. Alpine (musl) is not supported — use a glibc Node image such as node:22-bookworm-slim.

Keep the index and the model beside the code, so they survive container restarts and work offline. Set both variables for every magector command — index, search and the MCP server:

export MAGENTO_ROOT=/var/www/html MAGECTOR_MODELS=/var/www/html/.magector/models
npx -y magector@<version> index   # pin the version you deploy

Re-running index embeds only files whose content changed: a checkout or docker cp that only rewrote timestamps costs a content-hash comparison, not a re-embed, and a run that changes nothing leaves index.db untouched. Set MAGECTOR_NO_UPDATE=1 in images and CI so the CLI does not re-run itself as the latest npm version.

Build the index once, restore it where it is used

On slow disks (CI runners, network volumes) indexing and the PHP scan that find_implementors / find_event_dispatchers need take longest. Build both where the code is built — an image build — and restore them in the run:

# image build: index, read the PHP tree, write one archive
npx magector snapshot save /opt/magector.tar.gz /var/www/html
# run: restore it (the old index is kept as index.db.bak)
npx magector snapshot load /opt/magector.tar.gz /var/www/html

The archive (tar, gzip for .gz / .tgz) holds index.db, its manifest, the SONA state (index.sona), the descriptions DB (sqlite.db) and .magector/php-scan.json, plus a sha256 checksum per entry. A restore writes everything beside the live files and replaces them only when every entry is complete and matches its sha256 — computed while the archive is read, so nothing is read twice; a snapshot of another Magector version is refused. It can be restored into another path: the vector index stores paths relative to the root, and the PHP scan is rewritten for the new root. The method-chain enrichment (data.db) is not archived; run magento_enrich after a restore if you use magento_find_null_risks.

Whether anything is read again depends on the files' mtimes. In an image they are the build's, so neither load --update nor the MCP server reads a file again; load says so (it compares mtime and size, without reading). After a fresh checkout with new mtimes, --update hashes those files to find that their content is the same, and the MCP server reads the PHP tree again (a changed file with classes makes the scan unusable). save --no-index archives the existing index as it is. The models are not in the archive: keep MAGECTOR_MODELS in the image.

Constraining CPU usage during indexing

Indexing a large codebase can saturate the CPU during PHASE 2 (ONNX embedding generation). To keep a developer machine responsive while indexing, lower the thread count:

npx magector index --threads 2                  # use only 2 cores for both parsing and embedding
MAGECTOR_THREADS=2 npx magector index           # equivalent via env var
OMP_NUM_THREADS=2 npx magector index            # also honored as a fallback

The --threads flag and MAGECTOR_THREADS / OMP_NUM_THREADS env vars constrain both the rayon thread pool used by PHASE 1 (parallel AST parsing) and the ONNX intra-op thread pool used by PHASE 2 (embedding inference). Without any of them, ONNX uses half of the CPU cores and parsing uses all cores. The active thread source is logged at startup so you can verify it took effect:

INFO Rayon global pool: 2 threads (available: 16)
INFO ONNX intra_threads: 2 (available: 16, source: --threads flag)

For very large or CPU-constrained runs, you may also need to extend the wall-clock timeout (default 4 hours):

MAGECTOR_INDEX_TIMEOUT=28800000 npx magector index --threads 2   # 8 h timeout, 2 threads

Resume after timeout or interrupt

Indexing saves its progress to disk every 50 embedding batches. If the process is killed or times out mid-run, re-run npx magector index — it resumes from the last save:

npx magector index
# ♻️  Resuming from previous run: <N> vectors across <M> files already indexed
# ✓ Found <T> total files; <U> unchanged, <P> to process

The indexer compares the tree with the existing index (content hash per file) and embeds only files that are new or whose content changed since the last save; the vectors of unchanged files are kept. A resumed run also picks up files added to the tree since the previous run.

To force a full rebuild (e.g. to discard stale vectors), pass --force:

npx magector index --force

One indexer per root

Only one indexer writes a root's index at a time. magector index and magento_index take the lock file .magector/reindex.pid (created exclusively); a second run is refused while the PID in it is alive, including a process of another user, and magento_describe does not save the index while the lock is held. If a run reports another indexer and none is running (for example after a crash or a container restart), delete .magector/reindex.pid.

Directories that cannot be read are skipped instead of failing the run; on an incremental run, files already indexed under them are kept. A missing or unreadable root still fails.

MCP Server Tools

The MCP server exposes 48 tools for AI-assisted Magento 2 and Adobe Commerce development. Parameters marked * are required.

Output Format

Semantic result lists (magento_search, and the semantic block of the finder tools) are structured JSON. Structural tools (DI, events, diff, complexity, stats, grep, read and others) answer in Markdown/text.

{
  "results": [
    {
      "rank": 1,
      "score": 0.892,
      "path": "vendor/magento/module-catalog/Model/ProductRepository.php",
      "module": "Magento_Catalog",
      "className": "ProductRepository",
      "namespace": "Magento\\Catalog\\Model",
      "methods": ["save", "getById", "getList", "delete", "deleteById"],
      "magentoType": "repository",
      "fileType": "php",
      "badges": ["repository"],
      "snippet": "class ProductRepository implements ProductRepositoryInterface..."
    }
  ],
  "count": 1
}

Key fields:

  • methods -- list of method names in the class (avoids needing to read the file)

  • badges -- role indicators: plugin, controller, observer, repository, graphql-resolver, model, block

  • snippet -- first 300 characters of indexed content (top 3 results only)

  • Optional fields when known: methodName, area, description (LLM description) and codePreview (source lines for the top 3 PHP/PHTML results, or the full method body from magento_find_method)

How exact are the results?

Every answer is one of four kinds. The tables below say which kind each tool returns, and where it can return less than the codebase contains — the case to watch when you search for everything a change affects.

Kind

Meaning

Safe to conclude "nothing else"?

Exact

Structural, from the configuration / source files, resolved the way Magento resolves them at runtime

Yes, within the limits listed below

Superset (marked)

Every declaration, including ones that do not take effect — each marked: disabled, superseded, module disabled, does not run (with the reason)

Yes — drop what is marked

Fuzzy

Substring match on a short (non-namespaced) name; may include unrelated types

Yes, but filter the noise — pass a FQCN for an exact answer

Semantic

Ranked candidates from the vector index

No — use them to find a starting point

DI and events (pass a fully qualified name)

Tool

Returns

Can return less when …

magento_find_plugin

DI Plugin Registrations: superset (marked) — declarations on the class, its parents and interfaces, the real class of a virtual type; Effective state: exact merge by plugin name in module load order; per plugin method: does not run when the target method is final / static / non-public / never intercepted / missing, the class is final or implements NoninterceptableInterface. First block: semantic

a parent or interface cannot be read (no PHP file); plugins are added at runtime without di.xml

magento_find_preference

Exact: effective preference per area, superseded and ignored declarations, the class finally instantiated. Then semantic related files

app/etc/config.php is missing (load order is then approximated from <sequence>)

magento_find_observer

Superset (marked): every declaration incl. ones that only disable or modify an observer, with area; Effective state: exact merge by observer name

—

magento_find_event_flow, magento_find_event_dispatchers

Observers: as find_observer. Dispatchers: literal dispatch('event') calls, and names built from a property or class constant of the class that runs the code ($this->_eventPrefix . '_save_after'), resolved per concrete subclass through every trait and parent, from a di.xml constructor argument (area, virtual type); a name partly known only at runtime is listed as possible (controller_action_predispatch_*)

a part computed by a method call or a request value stays *; a dispatch added to a file that had none shows in the next session

magento_trace_dependency, magento_find_di_wiring

Exact: preferences, plugins (incl. inherited), virtual types resolving to the class (transitively), DI arguments that inject it (through virtual types, preferences, Factory, Proxy); plus the effective states above

the class is only type-hinted in a constructor without a di.xml argument (see impact_analysis)

magento_impact_analysis

DI references: exact (as above); API exposure: exact (webapi.xml services incl. interface → preference, schema.graphqls resolvers); PHP files: exact FQCN occurrences + semantic candidates; runtime callers: constructor-typed properties

the class is reached through an untyped variable, ObjectManager, or a factory result stored in a local variable

magento_find_implementors

Exact (FQCN): everything that is instanceof the type — direct implementors, extending interfaces, their implementors and all subclasses, transitively, with the path; preferences per area. Short name: fuzzy (implements naming the short name)

a class in the chain has no readable PHP file (e.g. generated code); a group holds more than 50 classes (the first 50 are listed, the rest counted)

With a short name (no namespace) the DI tools fall back to fuzzy matching — useful for exploring, not for a complete impact list.

Every tool answer is capped at 40,000 characters (MAGECTOR_MAX_OUTPUT_CHARS); a longer answer ends with Output truncated — narrow the query (full class name, targetMethod, a namespace) rather than read on.

Ambiguity is reported as a problem of the project, not of the tool: when two modules declare the same preference, plugin or observer, neither depends on the other (no <sequence>, no composer require) and swapping them changes the result, the outcome depends on incidental module order and can change with an update.

Other structural answers

Tool

Returns

Can return less when …

magento_find_table_usage

Superset: every PHP file and db_schema.xml with the table name as a string literal (ResourceModel _init, getTableName, setup patches) + semantic

the table name is built dynamically

magento_find_controller

Exact: routes.xml → module → controller class (admin routes under Controller/Adminhtml); then semantic

the route is registered by a custom router

magento_find_api

Exact: webapi.xml of the enabled modules merged as Magento merges it (route by url + method, service class / method attribute by attribute, ACL by ref) — every route whose URL contains the query, whose service method or class equals it, or whose service resolves to the given class; the class that runs (preference); then semantic

routes added at runtime (Magento_WebapiAsync's /async/… variants are noted, not listed)

magento_find_graphql

Exact over etc/schema.graphqls of the enabled modules, cut into types and merged as GraphQlReader does (types of one name merged in module order, extend type, interface fields copied into object types, a type written in a # comment is read — as Magento reads it); resolver, @cache identity, typeResolver; the schema readers registered besides it are named; then semantic

fields added by the other schema readers (CatalogGraphQl's EAV attribute readers: attributes flagged for GraphQL in the database) — named, not listed

magento_find_cron

Exact: crontab.xml merged by group + job, then the crontab defaults of config.xml (schedule, config path, run model) over it

schedules or jobs saved in the admin (core_config_data) — noted

magento_find_db_schema

Exact: db_schema.xml of the enabled modules + app/etc/db_schema.xml merged by table / column / referenceId; columns, keys and indexes with the names Magento creates, disabled elements marked, foreign keys to the table; legacy setup scripts: semantic

tables created by legacy setup scripts or at runtime; a table prefix (names shown without it)

magento_module_structure

Exact: every file of the module directory (from the module index, not guessed from the name), state and load position, and what the module declares in the merged configuration

—

magento_find_class

A virtual type name resolves exactly to its di.xml declaration and real class; PHP classes: semantic + filesystem fallback

—

magento_trace_config

system.xml definition and PHP readers (constant or literal path)

the path is concatenated at runtime

magento_grep, magento_ast_search

Exact text / AST matches

—

Configuration Magento rejects

The DI and event tools read what the files say. When Magento cannot load a file, or reads a value differently than written, they say so first: the answers of find_plugin, find_observer, find_preference, find_di_wiring, find_event_flow, trace_dependency, impact_analysis, find_class and batch start with a notice listing the rejected files of enabled modules, and values in the answer's files that do not take effect as written. magento_validate_config gives the details, with Magento's own messages:

Engine

Checks

Verified

native (MAGECTOR_PHP only)

Magento's classes on every file (Config\Dom — not well-formed XML fails in every mode; the DI / events converters and argument interpreters under Magento's ErrorHandler), then Magento's readers (ObjectManager\Config\Reader\Dom, Event\Config\Reader) on every area in production and developer mode — the merged configuration, as Magento validates it; other files against the schema they declare

is Magento

built-in (no PHP)

per file: the first libxml error (message and line), the converter and argument-interpreter rules ported from Magento, values read differently than written (observer disabled="1", non-integer sortOrder, text next to <item>s); per area: its files merged as Config\Dom merges them, then the same rules — a file another file completes loads, two files that load alone can fail together

against libxml 2.9.14 / Mage-OS 2.4.9 (scripts/verify-magento, mode config): same first fatal error on 2,000 files with syntax edits (1,384 not well-formed); same converter verdict on 3,000 files with value edits (2,518 converter exceptions; const names native only); built-in and native agree on every file and area of that project; merge (mode merge): the same merged document and verdict as Magento's readers on every DI / events area of a Mage-OS 2.4.9 and a Magento 2.4.5 project (30 areas) and on 15,008 merges of mutated files with their originals

The built-in check does not validate schemas (developer mode) and cannot check const / init_parameter arguments (PHP's defined()). The native check was verified on PHP 8.1, 8.3 and 8.4 (on Magento 2.4.5 with PHP 8.4 it gives the same result as with PHP 8.1).

The results are static analysis of the files. For a running installation, the object manager configuration read at runtime remains the reference — note that bin/magento dev:di:info lists plugins disabled with disabled="true" as active.

Search Tools

Tool

Parameters

Description

magento_search

query*, limit (default 10), moduleFilter, excludeModuleFilter, expand (default true), precise (default false)

Semantic search -- find any PHP class, method, XML config, template, GraphQL schema, or module README section by natural language

magento_find_class

className*, namespace

Find PHP class, interface, abstract class, or trait by name

magento_find_method

methodName*, className

Find method implementations across the codebase

Magento-Specific Finders

Tool

Parameters

Description

magento_find_config

query*, configType (di/routes/system/events/webapi/module/layout/other)

Find XML configuration (di.xml, events.xml, routes.xml, system.xml, webapi.xml, module.xml, layout)

magento_find_template

query*, area (frontend/adminhtml/base)

Find PHTML template files for frontend or admin rendering

magento_find_plugin

targetClass, targetMethod

Find interceptor plugins (before/after/around methods) and their di.xml declarations, with DI area; resolves plugin PHP files and extracts the interceptor method signatures

magento_find_fieldset

fieldset, aspect

Find fieldset.xml definitions controlling data copy between entities (order→quote, quote→order). Shows fields per aspect (to_order, to_edit)

magento_find_observer

eventName*

Find event observers and events.xml declarations

magento_find_preference

interfaceName*

Find DI preference overrides -- which class implements an interface

magento_find_controller

route*, area (frontend/adminhtml)

Find MVC controllers by frontend or admin route path

magento_find_block

query*

Find Block classes for view rendering

magento_find_graphql

query*, schemaType (type/query/mutation/interface/resolver)

Find GraphQL schema definitions, resolvers, types, queries, and mutations

magento_find_api

query*, method (GET/POST/PUT/DELETE)

Find REST/SOAP API endpoints in webapi.xml

magento_find_cron

jobName*

Find cron job definitions in crontab.xml

magento_find_db_schema

tableName*

Find database table definitions in db_schema.xml (declarative schema)

Flow & Dependency Tracing

Tool

Parameters

Description

magento_trace_flow

entryPoint*, entryType (auto/route/api/graphql/event/cron, default auto), depth (shallow/deep, default shallow)

Trace execution flow from an entry point (route, API, GraphQL, event, cron) -- maps controller → plugins → observers → templates with code snippets

magento_trace_shipping_chain

carrier

Trace the shipping rate chain: carriers → collectRates plugins → rate modifiers → totals collectors → fieldset mappings

magento_trace_dependency

className*, direction (resolve/dependents/both, default both)

Trace DI graph for a class/interface -- preferences, plugins, virtualTypes, argument overrides (parses all di.xml, no index needed)

magento_find_event_flow

eventName*

Trace event chain: dispatchers → observers → handler PHP classes (parses events.xml + vector search)

magento_find_event_dispatchers

eventName*, match (exact/strict/wildcard)

Where an event is dispatched: literal names and names built from the class that runs the code (catalog_product_save_after → AbstractModel::afterSave() for Catalog\Model\Product, $_eventPrefix in Product.php), one line per site and class; * in the name

magento_find_layout

query, handle

Find layout XML files by handle or content -- lists blocks, containers, and referenceBlock declarations

magento_trace_data_flow

attributeKey*, modelClass

Trace how a data attribute flows: setters (magic setter, setData, addData) and getters (magic getter, getData) across PHP and XML -- e.g. "who writes/reads custom_discounted_price_incl_tax on Quote\Address?"

magento_trace_call_chain

className, methodName, maxDepth (default 3)

Trace internal method call chain: follows $this->method(), $this->dep->method(), and dispatch() calls (with event → observer resolution) to build an execution tree

magento_trace_flow auto-detects the entry type from the pattern (/V1/... → API, snake_case → event, camelCase → GraphQL, path/segments → route), or override it with entryType. Use depth: "shallow" (entry + config + plugins) or depth: "deep" (adds observers, layout, templates, DI preferences).

Impact & Testing

Tool

Parameters

Description

magento_impact_analysis

className*

Analyze impact of changing a class -- finds use statements, DI references, direct instantiations, and type hints across the codebase

magento_find_test

className*, methodName

Find PHPUnit tests for a given class/method -- searches Test/ directories for coverage, mocks, and assertions

magento_find_implementors

interfaceName*

Find every class that is instanceof a given interface or class (implementors, extending interfaces, subclasses, transitively) and the <preference> declarations per area

magento_find_callers

methodName*, className

Find call sites of a method across PHP and XML files -- ->method() and ::method() calls

magento_find_di_wiring

className*

DI picture for a class: preferences, plugins, constructor args, virtual types, and argument overrides from di.xml

Diagnostics

Tool

Parameters

Description

magento_error_parser

error*

Parse Magento error messages and map to root cause, affected files, and fix suggestions (13 known patterns)

magento_performance_profile

subsystem*, threshold (default 0)

Profile a Magento subsystem (checkout_totals, order_place, product_save, etc.) for performance bottlenecks -- plugins, observers, and complexity hotspots

magento_validate_config

path, engine (auto/native/builtin)

Configuration XML the way Magento loads it: files it rejects in every mode, developer-mode (schema) failures per area, values read differently than written — with Magento's messages. Native through PHP (MAGECTOR_PHP), otherwise built-in. See Configuration Magento rejects

Analysis Tools

Tool

Parameters

Description

magento_analyze_diff

commitHash, staged (default true)

Risk scoring and change classification of a commit (commitHash, a git ref) or of the staged changes, in MAGENTO_ROOT; an invalid ref or a root that is not a git repository is reported as an error

magento_complexity

module, path, threshold (default 0)

Cyclomatic complexity, function count, and line count of a module (Vendor_Module) or of a path under MAGENTO_ROOT

Utility Tools

Tool

Parameters

Description

magento_module_structure

moduleName*

Show module structure -- controllers, models, blocks, plugins, observers, configs

magento_index

path

Re-index the codebase, or the directory given in path, without blocking the server. The index is always written to the configured MAGECTOR_DB, so a path other than the project root replaces the project's index with that tree. Returns the last 16 KB of the indexer output (the last 4 MB of each output stream is logged to .magector/magector.log) and starts the method-chain enrichment in the background. The serve process picks up the new index at its next watcher check

magento_describe

force (default false)

Generate LLM descriptions for di.xml files (requires ANTHROPIC_API_KEY), stored in .magector/sqlite.db, then re-index the described files

magento_stats

—

View index statistics

magento_batch

queries* (max 10 items of {tool, args})

Run up to 10 calls in parallel in one MCP round trip. Supported tools: magento_search, find_class, find_method, find_plugin, find_observer, find_config, find_event_flow, find_di_wiring, find_callers, module_structure, trace_dependency, impact_analysis, trace_config, grep, read, ast_search, find_dataobject_issues, find_null_risks (all with the magento_ prefix); any other tool returns "Unsupported batch tool"

magento_grep

pattern*, path, include (default *.php), ignoreCase (default false), maxResults (default 50), context (default 4), filesOnly (default false)

Exact text/regex search across PHP/XML/PHTML files. Runs in the Rust serve process, falling back to grep -rn -E. filesOnly works like grep -l

magento_read

path*, startLine, endLine, methodName

Read a file, a line range, or only one method (methodName), which returns far fewer tokens than the whole file

magento_trace_api

url, interfaceName, method (GET/PUT/POST/DELETE)

Trace a REST/GraphQL API endpoint from URL to implementation: webapi.xml → service interface → DI preference → method body

magento_trace_config

configPath, keyword

Trace a config path end-to-end: system.xml admin definition → PHP classes that consume the value → DB values from config-data exports. Accepts an exact path or a keyword

magento_find_trigger

triggerName, tableName

Find database triggers across the codebase

magento_find_table_usage

tableName*

Find all PHP code referencing a specific database table

Null-Safety Analysis

Tool

Parameters

Description

magento_ast_search

pattern* (dataobject-set-null/unchecked-method-chain), path, maxResults (default 50)

Structural PHP code search using tree-sitter. Named patterns: dataobject-set-null (setX(null) anti-pattern), unchecked-method-chain ($this->dep->method() chains). Pattern is an enum, not free text. Runs in the Rust serve process

magento_enrich

—

Build the method-chain enrichment index. Scans vendor/ PHP files for ->firstMethod()->secondMethod() chains and detects null guards in surrounding code. Stores results in .magector/data.db (SQLite, via Rust serve). Runs automatically after magento_index

magento_find_null_risks

firstMethod, limit (default 100)

Query the enrichment index for method chains without null guards -- an indexed SQLite lookup instead of file scanning. Pass firstMethod to filter (e.g., "getPayment" → all ->getPayment()->anything() without null guard). Requires magento_enrich

magento_find_dataobject_issues

path, maxResults (default 100)

Detect the setX(null) anti-pattern on Magento DataObject subclasses. setX(null) stores ['x' => null] in _data — hasX() (via array_key_exists) returns true even when the value is null, creating false-positive guard conditions. Uses tree-sitter

Search Behaviour

  • Hybrid BM25+vector search -- combines text frequency scoring with semantic vector similarity

  • Query expansion -- magento_search expands queries with Magento domain synonyms (plugin → interceptor, checkout → cart/quote/totals, etc.); turn it off with expand: false

  • Module filtering -- moduleFilter / excludeModuleFilter on magento_search limit results by vendor/module pattern. Accepts a single string or array of strings. Supports wildcards, e.g., "Vendor_*" or ["Acme_PaymentGateway", "Acme_FreeShipping"]

  • Non-blocking automatic reindex -- when the MCP server starts an index itself (no index, or an incompatible one), the old index stays usable; the new one is built to a temp path and swapped in on completion (the old one is kept as .bak). magento_index and magector index write the index in place

Tool Cross-References

Each tool description includes "See also" hints to help AI clients chain tools:

graph LR
  cls["find_class"] --> plg["find_plugin"]
  cls --> prf["find_preference"]
  cls --> mtd["find_method"]
  cfg["find_config"] --> obs["find_observer"]
  cfg --> prf
  cfg --> api["find_api"]
  plg --> cls
  plg --> mtd
  tpl["find_template"] --> blk["find_block"]
  blk --> tpl
  blk --> cfg
  dbs["find_db_schema"] --> cls
  gql["find_graphql"] --> cls
  gql --> mtd
  ctl["find_controller"] --> cfg
  trc["trace_flow"] -.-> ctl
  trc -.-> plg
  trc -.-> obs
  trc -.-> tpl
  trc -.-> api
  trc -.-> gql
  dep["trace_dependency"] --> prf
  dep --> plg
  evf["find_event_flow"] --> obs
  imp["impact_analysis"] --> dep
  imp --> cls
  tst["find_test"] --> cls
  err["error_parser"] --> dep
  lay["find_layout"] --> blk

  style cls fill:#4a90d9,color:#fff
  style mtd fill:#4a90d9,color:#fff
  style cfg fill:#e8a838,color:#000
  style plg fill:#d94a4a,color:#fff
  style obs fill:#d94a4a,color:#fff
  style prf fill:#e8a838,color:#000
  style api fill:#e8a838,color:#000
  style tpl fill:#68b684,color:#000
  style blk fill:#68b684,color:#000
  style dbs fill:#9b59b6,color:#fff
  style gql fill:#9b59b6,color:#fff
  style ctl fill:#4a90d9,color:#fff
  style trc fill:#2ecc71,color:#000

Query Examples

magento_search("how are checkout totals calculated")
magento_search("product price with tier pricing and catalog rules")
magento_find_class("ProductRepositoryInterface")
magento_find_method("getById")
magento_find_config("di.xml plugin for ProductRepository")
magento_find_plugin({ targetClass: "Topmenu" })
magento_find_observer("sales_order_place_after")
magento_find_preference("StoreManagerInterface")
magento_find_api("/V1/orders")
magento_find_controller("catalog/product/view")
magento_find_graphql("placeOrder")
magento_find_db_schema("sales_order")
magento_find_cron("indexer")
magento_find_block("cart totals")
magento_find_template("minicart")
magento_analyze_diff({ commitHash: "abc123" })
magento_complexity({ module: "Magento_Catalog", threshold: 10 })
magento_describe()
magento_trace_flow({ entryPoint: "checkout/cart/add", depth: "deep" })
magento_trace_flow({ entryPoint: "/V1/products" })
magento_trace_flow({ entryPoint: "placeOrder", entryType: "graphql" })
magento_trace_flow({ entryPoint: "sales_order_place_after" })
magento_trace_data_flow({ attributeKey: "custom_discounted_price_incl_tax", modelClass: "Quote\\Address" })
magento_find_event_dispatchers({ eventName: "custom_discount_rule_validation_before" })
magento_find_implementors({ interfaceName: "ProductRepositoryInterface" })
magento_find_callers({ methodName: "collectTotals", className: "TotalsCollector" })
magento_find_di_wiring({ className: "CartManagementInterface" })
magento_trace_call_chain({ className: "Magento\\Quote\\Model\\QuoteManagement", methodName: "submit" })

Supported Platforms

Pre-built binaries are provided for the following platforms:

Platform

Architecture

Package

macOS

ARM64 (Apple Silicon)

@magector/cli-darwin-arm64

Linux

x86_64

@magector/cli-linux-x64

Linux

ARM64

@magector/cli-linux-arm64

Windows

x86_64

@magector/cli-win32-x64

Note: macOS Intel (x86_64) is not supported as a pre-built binary. Intel Mac users can build from source.

Validation

Magector is checked at two levels:

  1. Automated tests -- npm test runs the Node.js test files (unit tests, MCP integration over stdio JSON-RPC, reindex lock, serve start and request ids, DI parsing and resolution, event dispatch resolution, config models, validate_config, trace_graphql, index snapshot). cd rust-core && cargo test --release runs the Rust unit tests. CI runs both (see Testing).

  2. Rust-level validation -- magector-core validate runs 557 validation queries (defined in rust-core/src/validation.rs) against Magento 2.4.7 (downloaded when no -m is given) or the root given with -m.

Historical accuracy result

tests/results/accuracy-report.json records an E2E MCP accuracy run from 2 April 2026: 99.2 / 100 (grade A+) on 101 queries across 16 tools, 101/101 passed, precision 98.4%, MRR 99.5%, NDCG@10 98.8%. That run used an earlier build with the all-MiniLM-L6-v2 embedding model, before the switch to bge-small-en-v1.5. The test suite that produced it has since been removed from the repository, so the result cannot be re-run from the current repo and is not a statement about the current build.

Project Structure

magector/
├── src/                  # Node.js: CLI (cli.js), MCP server (mcp-server.js), binary and model
│   │                     #   resolution, init/IDE setup, DI/config readers, PHP scan, snapshots
│   ├── php/              # PHP program for the native magento_validate_config
│   ├── templates/        # IDE rules templates (CLAUDE.md section, Cursor rules)
│   └── validation/       # Legacy JS validation/benchmark scripts (broken: import removed modules)
├── tests/                # Node.js tests run by `npm test` (scripts/run-tests.mjs), fixtures, results/
├── rust-core/            # Rust core (magector-core)
│   ├── src/              # main.rs (CLI + serve), indexer, embedder, vectordb, watcher, ast,
│   │                     #   magento (pattern detection), describe, sona, datadb, validation
│   ├── queries/          # tree-sitter queries
│   └── models/           # dev fallback model directory (tokenizer.json committed)
├── platforms/            # npm packages for the platform binaries (built by CI, not committed)
├── scripts/              # run-tests.mjs, sync-optional-deps.mjs, setup.sh, verify-magento/
├── config/               # example MCP config for a source checkout (its paths must be edited)
├── docs/                 # verification notes
├── .github/workflows/    # ci.yml (tests), release.yml (cross-compile + publish)
├── CHANGELOG.md
├── package.json
└── LICENSE

How It Works

1. Indexing

Magector scans every .php, .js, .xml, .phtml, and .graphqls file in a Magento 2 or Adobe Commerce codebase (files up to 100 KB), plus each module README at app/code/<Vendor>/<Module>/README.md:

  1. AST parsing -- Tree-sitter extracts class names, namespaces, methods, inheritance, and interface implementations from PHP and JavaScript files

  2. Pattern detection -- Identifies Magento file types by path and AST: controllers, models, repositories, plugins, observers, blocks, GraphQL resolvers, cron, setup, API interfaces, configuration XML types, and more

  3. Search text enrichment -- Combines AST metadata with Magento pattern keywords to create the text that is embedded

  4. Description enrichment -- If a descriptions SQLite DB is present, LLM-generated descriptions are prepended to the embedding text as "Description: {text}\n\n", placing DI concepts (preferences, plugins, virtual types, subsystem names) within the 256 tokens the model reads

  5. Embedding -- ONNX Runtime generates 384-dimensional vectors with bge-small-en-v1.5 (mean-pooled, L2-normalised, first 256 tokens)

  6. Indexing -- Vectors are stored in index.db; up to 300k of them a search compares the query with every vector (exact, nothing to build at start-up), above that an HNSW graph finds approximate nearest neighbors

Each source file produces one vector. A module README is split into sections of at most 800 characters, one vector each, led by the module name and the section heading; magento_find_class and magento_find_method never return README vectors. After upgrading, run magector index --force to re-split READMEs indexed by an older version (otherwise a README is re-split when it changes).

2. Searching

  1. magento_search expands the query with Magento synonyms (e.g. "controller" adds "action class", "execute method", "route handler"; disable with expand: false)

  2. The Rust core prefixes the query with Represent this sentence: and embeds it into the same 384-dimensional space

  3. The nearest vectors are found by cosine similarity (every vector compared up to 300k, the HNSW graph above)

  4. Hybrid reranking boosts results with keyword matches in path and search text

  5. SONA adjustment -- learned pattern boosts raise result types that followed similar searches before

  6. Results are returned as structured JSON with file path, class name, methods, role badges, and (top results) a content snippet

3. Persistent Serve Mode

The MCP server spawns a persistent Rust process (magector-core serve) that keeps the ONNX model and the vector index loaded in memory. Queries are sent as JSON over stdin and responses returned via stdout, so a query does not load the model or the index. Up to 300k vectors there is no search graph to build at start; on a 50k-vector index serve was ready 0.7 s after it started (CHANGELOG 2.22.0). If it is not ready, a search waits for it up to MAGECTOR_SERVE_WAIT_MS, then runs a single-shot magector-core search (asynchronous, at most 20 s), so a tool answers inside the MCP client's 60 s. One serve process per project: the first MCP instance starts it and the others join it over .magector/serve.sock — also instances in other containers sharing .magector (an MCP gateway starting one per session), since the lock records the PID namespace of its holder.

flowchart LR
  subgraph startup ["Startup (once)"]
    S1["Load Model"] --> S2["Load Index"] --> S3["Ready Signal"]
  end
  startup --> query
  subgraph query ["Per Query"]
    Q1["stdin JSON"] --> Q2["Embed"] --> Q3["Vector Search"] --> Q4["Rerank"] --> Q5["stdout JSON"]
  end
  subgraph fallback ["Fallback (serve not ready)"]
    F1["single-shot search<br/>(async, ≤20 s)"]
  end

  style startup fill:#e8f4e8,color:#000
  style query fill:#e8e8f4,color:#000
  style fallback fill:#f4e8e8,color:#000

4. File Watcher (Incremental Re-indexing)

When the serve process is started with --magento-root, a background thread polls the filesystem for changes: every 300 s when started by the MCP server (MAGECTOR_WATCH_INTERVAL), every 60 s by default when magector-core serve is run directly (--watch-interval). Changed files are re-indexed without restarting the server.

Since hnsw_rs does not support point deletion, Magector uses a tombstone strategy: old vectors for modified/deleted files are marked as tombstoned and filtered out of search results. New vectors are appended. When more than 20% of the vectors are tombstoned, they are purged; the HNSW graph, used only above 300k vectors, is rebuilt.

flowchart LR
  W1["Sleep (interval)"] --> W2["Scan Filesystem"] --> W3{"Changes?"}
  W3 -->|No| W1
  W3 -->|Yes| W4["Tombstone Old Vectors"] --> W5["Parse + Embed New Files"] --> W6["Append Vectors"] --> W7{"Tombstone > 20%?"}
  W7 -->|Yes| W8["Compact<br/>(purge tombstones)"] --> W9["Save to Disk"]
  W7 -->|No| W9
  W9 --> W1

  style W4 fill:#f4e8e8,color:#000
  style W5 fill:#e8f4e8,color:#000
  style W8 fill:#e8e8f4,color:#000

5. MCP Integration

The MCP server delegates search and index operations to the Rust core binary. Analysis tools (diff, complexity) use ruvector JS modules directly.

sequenceDiagram
  participant Dev
  participant AI
  participant MCP
  participant Rust
  participant VectorDB

  Dev->>AI: "checkout totals?"
  AI->>MCP: magento_search(...)
  MCP->>Rust: JSON query
  Rust->>VectorDB: embed + search
  VectorDB-->>Rust: candidates
  Rust-->>MCP: JSON results
  MCP-->>AI: paths, methods, badges
  AI-->>Dev: TotalsCollector.php

6. SONA Feedback Learning

The MCP server tracks sequences of tool calls and sends feedback signals to the Rust process, which adjusts search result rankings based on observed usage patterns.

How it works: The Node.js SessionTracker watches for follow-up tool calls after magento_search. If a user searches and then calls magento_find_plugin, SONA learns that similar queries should boost plugin results. The learned weights are persisted to a .sona file next to the index.

MCP Call Sequence

Signal

Effect on Future Searches

magento_search → magento_find_plugin (within 30s)

refinement_to_plugin

Boosts plugin results

magento_search → magento_find_class (within 30s)

refinement_to_class

Boosts class matches

magento_search → magento_find_config (within 30s)

refinement_to_config

Boosts config/XML results

magento_search → magento_find_observer (within 30s)

refinement_to_observer

Boosts observer results

magento_search → magento_find_controller (within 30s)

refinement_to_controller

Boosts controller results

magento_search → magento_find_block (within 30s)

refinement_to_block

Boosts block results

magento_search → magento_trace_flow (within 30s)

trace_after_search

Boosts controller results

magento_search(Q1) → magento_search(Q2) (within 60s)

query_refinement

Sent to serve, which ignores it (no effect)

Characteristics:

  • Score adjustments are capped at ±0.15 so they do not override semantic similarity

  • Learning rate decays with repeated observations (diminishing returns)

  • Learned weights are keyed by normalized, order-independent query term hashes

  • 3-tier scoring with negative learning: positive signals boost the followed feature type, mild negative learning (0.1×) demotes unrelated types

  • Always active -- no feature flags or build-time opt-in required

  • Persisted via bincode next to the index, with its extension replaced (.magector/index.db → .magector/index.sona); the V1 → V2 persistence format is upgraded on load

MicroLoRA + EWC++ (present, not trained online)

rust-core/src/sona.rs also contains embedding-level adaptation:

Component

Parameters

Purpose

MicroLoRA

1536 (rank-2, 2×384×2)

Adjusts the query embedding before vector search

EWC++

Fisher diagonal (1536 values, one per LoRA parameter)

Regularisation against forgetting (λ=2000)

adjust_query_embedding() applies the LoRA transform + L2 normalization at search time, with a cosine similarity guard (≥0.90) that skips destructive adjustments. learn_with_embeddings(), the only function that trains the adapter, is called only from tests: the serve feedback command does pattern learning only. The adapter is therefore not trained in normal use.

A January 2026 evaluation (tests/results/sona-eval-report.json, 180 evaluation queries after 3 training rounds) found no measurable ranking change: MRR −0.002, 178 of 180 queries kept their rank. The script that produced it has since been removed from the repository.

7. LLM Description Enrichment

Magector can generate natural-language descriptions of di.xml files using the Anthropic API and embed them into the vector index, so queries about dependency injection can match di.xml files by their described purpose.

Workflow:

# 1. Generate descriptions (incremental — only re-describes changed files)
ANTHROPIC_API_KEY=sk-... npx magector describe /path/to/magento

# 2. Re-index with descriptions embedded into vectors
npx magector index /path/to/magento

Or via the MCP tool: magento_describe() generates descriptions and re-indexes the described files in one step.

How it works: Each di.xml file is sent to Claude Sonnet (claude-sonnet-4-5-20250929 by default) with a prompt aimed at search retrieval. The resulting description is stored in a SQLite database (.magector/sqlite.db). During indexing, descriptions are prepended to the embedding text as "Description: {text}\n\n" before the raw file content, placing the described terms (preferences, plugins, virtual types, subsystem names) within the model's 256-token window.

Magento Patterns Detected

mindmap
  root((Patterns))
    PHP
      Controller
      Model
      Repository
      Block
      Helper
      API interface
      Setup / Patch
      Console
      Cron
    Interception
      Plugin
      Observer
    XML
      di.xml
      events.xml
      webapi.xml
      system.xml
      acl.xml
      crontab.xml
      db_schema.xml
      layout
    Frontend
      Template
      JavaScript
      GraphQL
    Docs
      Module README

Each file gets a Magento type from its path (rust-core/src/magento.rs); PHP files also get pattern flags from their AST (rust-core/src/ast.rs):

Pattern

Detection Method

Example

Controller

Path under Controller/; AST: implements *ActionInterface, extends *Action, or has execute()

Controller/Adminhtml/Order/View.php

Model

Path under Model/; AST: extends AbstractModel / AbstractDb

Model/Product.php

Repository

Path under Model/ containing "repository"; AST: implements *RepositoryInterface, or class / namespace contains Repository

Model/ProductRepository.php

Block

Path under Block/; AST: extends Template / AbstractBlock

Block/Product/View.php

Plugin

Path under Plugin/; AST: before/after/around methods, or class / namespace contains Plugin

Plugin/Product/SavePlugin.php

Observer

Path under Observer/; AST: implements ObserverInterface

Observer/ProductSaveObserver.php

GraphQL Resolver

Path containing "resolver" in a GraphQL module; AST: implements ResolverInterface / BatchResolverInterface

Model/Resolver/Products.php

API interface

Path under Api/; AST: an interface in an Api namespace

Api/ProductRepositoryInterface.php

Helper

Path under Helper/

Helper/Data.php

Cron

Path under Cron/

Cron/CleanExpiredQuotes.php

Console Command

Path under Console/

Console/Command/IndexerReindex.php

Setup Patch

Path under Setup/; AST: implements *PatchInterface or an Install/Upgrade interface

Setup/Patch/Data/AddAttribute.php

di.xml

File name

etc/di.xml, etc/frontend/di.xml

events.xml

File name

etc/events.xml

webapi.xml

File name

etc/webapi.xml

system.xml

File name

etc/adminhtml/system.xml

acl.xml

File name

etc/acl.xml

crontab.xml

File name

etc/crontab.xml

db_schema.xml

File name

etc/db_schema.xml

layout XML

.xml under layout/

view/frontend/layout/catalog_product_view.xml

Template

.phtml extension

view/frontend/templates/product/view.phtml

JavaScript

.js with AMD/ES6 detection

view/frontend/web/js/view/minicart.js

GraphQL Schema

.graphqls extension

etc/schema.graphqls

Module README

app/code/<Vendor>/<Module>/README.md (magentoType readme)

app/code/Acme/Import/README.md

Configuration

IDE Rules

npx magector init (or setup) writes .cursor/rules/magector.mdc for Cursor and a Magector section in CLAUDE.md for Claude Code — for the detected IDE, or both when neither is detected. The rules instruct the AI to:

  1. Use Magector MCP tools before reading files manually

  2. Write effective semantic queries

  3. Follow Magento development patterns

  4. Interpret search results correctly

Excluding Directories (.magectorignore)

Magector skips these during indexing:

  • vendor/bin/, pub/static/, dev/tests/, dev/tools/ (by path from the root)

  • any directory named node_modules, .git, var, generated, Test, Tests, test, tests, _files, fixtures or performance-toolkit

  • files larger than 100 KB, and directories that cannot be read

vendor/ itself is indexed: on a composer install, Magento core lives in vendor/magento.

For project-specific exclusions, create a .magectorignore file in your Magento project root:

# .magectorignore — additional directories to exclude from Magector indexing
# One directory name or path prefix per line (no wildcards, no negation)

# Custom exclusions
pub/media
setup
update
phpserver
bin
lib/internal

Pattern rules:

  • Lines starting with # are comments

  • Empty lines are ignored

  • Trailing slashes are stripped (vendor/ → vendor)

  • Patterns without / match directory names anywhere in the tree

  • Patterns with / match relative paths from the project root (the path itself and everything under it)

  • Patterns match directories only

Config Data (core_config_data exports)

The magento_trace_config tool can show actual database config values alongside code analysis. Export your core_config_data table as JSON and place files in .magector/config-data/.

Each *.json file in that directory must hold a JSON array of objects with the fields scope, scope_id, path and value:

[
  {"scope": "default", "scope_id": 0, "path": "web/secure/base_url", "value": "https://shop.example/"},
  {"scope": "websites", "scope_id": 1, "path": "payment/checkmo/active", "value": null}
]

With the mysql client, export the table as tab-separated text (-B) and convert it with Python:

mysql -u user -p magento_db -B -e "SELECT scope, scope_id, path, value FROM core_config_data" \
  | python3 -c 'import csv,json,sys; r=list(csv.DictReader(sys.stdin, delimiter="\t", quoting=csv.QUOTE_NONE)); [d.update(scope_id=int(d["scope_id"]), value=None if d["value"]=="NULL" else d["value"]) for d in r]; json.dump(r, sys.stdout, indent=2)' \
  > .magector/config-data/CZ-production.json

In -B output SQL NULL appears as the text NULL (converted to null above), and tabs, newlines and backslashes inside values are escaped (\t, \n, \\). Any other tool that writes the same array works too.

File naming: the file name without .json is the environment label shown in the answer; the convention is {country}-{environment}.json, e.g.:

  • CZ-production.json

  • SK-staging.json

  • IT-production.json

When magento_trace_config traces a config path, it looks up values from all exports and shows them per environment. A file that is not valid JSON is skipped; a JSON value that is not an array counts as empty. The exports are read once per MCP server process: restart the server after adding or changing a file.

Model Configuration

The Rust core indexes and searches with bge-small-en-v1.5 (384 dimensions). It loads bge-small-en-v1.5.onnx and tokenizer.json from its model directory and downloads both from Hugging Face (BAAI/bge-small-en-v1.5) when either is missing; an interrupted download is retried on the next start. The Node.js CLI and MCP server pick that directory in this order: MAGECTOR_MODELS if it already holds the model files the Node side checks for (see below), then ~/.magector/models, then rust-core/models in a source checkout. When none is ready, the CLI downloads into MAGECTOR_MODELS (or ~/.magector/models); the MCP server falls back to MAGECTOR_MODELS, else ./models. A direct magector-core call uses -c (default ./models in the working directory):

magector-core index -m /path/to/magento -c /custom/model/path

The Node.js side (src/model.js) checks the model directory for all-MiniLM-L6-v2.onnx and tokenizer.json and downloads them from Hugging Face (sentence-transformers/all-MiniLM-L6-v2) when they are missing. It uses these files only to decide whether the directory is ready; the Rust core never loads the MiniLM model, and on its first run it replaces tokenizer.json with the bge tokenizer. As a result, the model directory also holds an unused all-MiniLM-L6-v2.onnx (about 86 MB).

Development

Building from Source

Requires Node.js 20+ and a stable Rust toolchain.

git clone https://github.com/krejcif/magector.git
cd magector

# Install Node.js dependencies
npm install

# Build the Rust core
cd rust-core
cargo build --release
cd ..

# The CLI finds the dev binary at rust-core/target/release/magector-core
node src/cli.js help

Building

# Rust core
cd rust-core
cargo build --release

# Run unit tests
cargo test --release

# Run validation (557 queries; downloads Magento 2.4.7 when -m is not given)
cargo run --release -- validate

Testing

# All Node.js test files listed in scripts/run-tests.mjs; continues past failures,
# prints a per-file summary and exits 1 if any file failed. Search tests are skipped
# when no index exists.
npm test

# Single suites
npm run test:unit
npm run test:integration          # MCP integration tests (tests/mcp-server.test.js)
npm run test:no-index             # MCP integration tests with the search tools skipped
npm run test:reindex-lock
npm run test:serve-start
npm run test:trace-graphql
npm run test:di-resolution
npm run test:di-parsing
npm run test:validate-config
npm run test:config-models
npm run test:dispatch-resolution
npm run test:index-snapshot

# Tests that are not part of npm test
node tests/mcp-sona.test.js      # SONA feedback integration
node tests/trace-flow.test.js     # magento_trace_flow (needs an index)

# Rust unit tests
cd rust-core && cargo test --release

# Rust validation against an existing Magento checkout
cd rust-core && cargo run --release -- validate -m ./magento2 --skip-index

tests/mcp-serve-ids.test.js has no script of its own; it runs as part of npm test.

CI (.github/workflows/ci.yml) runs on every pull request and every push to main: one job runs npm test on Node 22 with MAGECTOR_AUTO_INDEX=0 and a cached model directory, the other runs cargo test --release in rust-core.

Adding New Magento Patterns

  1. Add pattern detection in rust-core/src/magento.rs (path) and/or rust-core/src/ast.rs (AST)

  2. Add search text enrichment in rust-core/src/indexer.rs

  3. Add validation cases in rust-core/src/validation.rs

  4. If the pattern changes an MCP answer, add a case to tests/mcp-server.test.js

  5. Rebuild and verify:

cd rust-core
cargo build --release
cargo test --release
./target/release/magector-core validate -m ./magento2 --skip-index
cd .. && npm test

Adding MCP Tools

  1. Define the tool schema in src/mcp-server.js (ListToolsRequestSchema handler)

  2. Include keyword-rich descriptions and cross-tool "See also" references

  3. Implement the handler in the CallToolRequestSchema handler

  4. Return semantic result lists via formatSearchResults()

  5. Add the tool to the expected-tool list and a call test in tests/mcp-server.test.js

  6. Test with Claude Code or the MCP inspector

Technical Details

Embedding Model

  • Model: BAAI/bge-small-en-v1.5

  • Dimensions: 384

  • Max sequence length: 256 tokens

  • Query prefix: Represent this sentence:

  • Pooling: Mean pooling with attention mask

  • Normalization: L2 normalized

  • Runtime: ONNX Runtime (via ort crate), CPU

Vector Index

  • Algorithm: exact cosine search over all vectors up to 300,000; above that an HNSW graph (hnsw_rs), built in parallel on first use or at serve warm-up

  • HNSW parameters: M=32, max_layers=16, ef_construction=200; ef_search = max(2×k, 50), or max(2×candidates, 64) for hybrid search

  • Distance metric: Cosine similarity

  • Hybrid search: Semantic nearest-neighbor + keyword reranking in path and search text + SONA pattern boosts

  • Incremental updates: Tombstone soft-delete + compaction above 20% tombstones

  • Persistence: Bincode V2 binary serialization (V1 files are read), written to a temp file, fsync'd, then renamed

Index Structure

Each indexed source file produces one vector entry (a module README produces one per section) with this metadata (rust-core/src/vectordb.rs):

pub struct IndexMetadata {
    pub path: String,
    pub file_type: String,              // php, xml, template, javascript, graphql, markdown
    pub magento_type: Option<String>,   // controller, model, block, plugin, readme, ...
    pub class_name: Option<String>,
    pub class_type: Option<String>,
    pub method_name: Option<String>,
    pub methods: Vec<String>,
    pub namespace: Option<String>,
    pub module: Option<String>,
    pub area: Option<String>,
    pub extends: Option<String>,
    pub implements: Vec<String>,
    pub is_controller: bool,
    pub is_repository: bool,
    pub is_plugin: bool,
    pub is_observer: bool,
    pub is_model: bool,
    pub is_block: bool,
    pub is_resolver: bool,
    pub is_api_interface: bool,
    // JavaScript specific
    pub is_ui_component: bool,
    pub is_widget: bool,
    pub is_mixin: bool,
    pub js_dependencies: Vec<String>,
    pub search_text: String,
}

Performance Design

  • Persistent serve mode -- the Rust process keeps the ONNX model and the vector index in memory, behind a stdin/stdout JSON protocol

  • Query cache -- the MCP server caches up to 200 search results; when full, the oldest entry is evicted first

  • Hybrid reranking -- combines semantic similarity with keyword matching

  • Batched ONNX embedding -- 256 texts per inference call by default (MAGECTOR_BATCH_SIZE, --batch-size)

  • Thread limit -- ONNX intra-op threads default to half the CPU cores; --threads / MAGECTOR_THREADS / OMP_NUM_THREADS limit both ONNX and rayon

  • Thread-local AST parsers -- each rayon thread gets its own tree-sitter parser (no mutex contention)

  • Bincode persistence -- binary index format, written to a temp file, fsync'd, then renamed, so a crash does not leave a truncated index

  • Exact search up to 300k vectors -- no graph to build at start-up; above 300k the HNSW graph is sized to the vector count and built with parallel insertion on first use

Roadmap

Not implemented yet:

  • Method-level chunking (per-method vectors for direct method search; today a PHP file is one vector)

  • Query intent classification (auto-detect "give me XML" vs "give me PHP")

  • Filtered search by file type at the vector level

  • VSCode extension

  • Web UI for browsing results

Troubleshooting

All MCP server activity is logged to .magector/magector.log in the Magento project root. The log persists across MCP restarts and uses the format:

[2026-04-12T18:30:00.000Z] [LEVEL] message

Log Levels

Level

Meaning

INFO

Normal operations: startup config, tool completion, search fallbacks, background enrichment start/finish

WARN

Recoverable issues: slow grep queries (>5s), missing data.db, file read errors, serve process disconnects, failed enrichment

ERR

Failures: AST query errors, serve process errors, tool execution errors

REQ

Every tool call with full input parameters (JSON)

RES

Tool completion with elapsed time in milliseconds

QUERY

Rust serve process queries (search, feedback)

CACHE

Search cache hits

INDEX

Background reindex progress

SERVE

Rust serve process stderr (watcher events, model loading)

FATAL

Server startup failures

Common Diagnostic Commands

# Recent errors
grep '\[ERR\]\|\[FATAL\]' .magector/magector.log | tail -20

# Tool timing (find slow tools)
grep '\[RES\]' .magector/magector.log | tail -20

# Background enrichment after magento_index
grep 'Auto-enrich' .magector/magector.log | tail -20

# AST search (tree-sitter) issues
grep 'ast_search:' .magector/magector.log | tail -20

# Batch query breakdown (per-tool timing)
grep 'batch\[' .magector/magector.log | tail -20

# Slow grep queries
grep 'grep: slow\|grep: timed' .magector/magector.log | tail -20

# Full startup sequence
grep 'server starting\|Config:\|primary\|Serve process' .magector/magector.log | tail -30

What Gets Logged

Every tool call logs [REQ] with input parameters and [RES] with elapsed time. Additionally:

  • magento_ast_search — tree-sitter pattern, target path, execution time, result count, query errors

  • magento_batch — query list on entry, per-sub-tool timing and errors

  • magento_grep — slow query warnings (>5s), timeout detection

  • magento_read — file-not-found with error codes, failed method extractions

  • magento_index — the indexer output, up to the last 4 MB of each stream (the tool itself returns only the last 16 KB)

  • Enrichment — Auto-enrich: starting…, Auto-enrich complete: N files, M chains or Auto-enrich failed: …; magento_enrich and magento_find_null_risks log only their [REQ] / [RES] lines

"an indexer (PID N) is writing the index" / "Another indexing process … is already running"

Another magector index or magento_index holds .magector/reindex.pid. Wait for it to finish. If no indexer is running (for example after a crash or a container restart), delete .magector/reindex.pid.

magento_index output is cut off

The tool returns at most the last 16 KB of the indexer's output, prefixed with …(truncated; full output in .magector/magector.log). The log holds the indexer output up to the last 4 MB of each stream.

Module README sections missing or too coarse

READMEs indexed by an older version are re-split only when they change. Run npx magector index --force to re-split all of them.

License

MIT License. See LICENSE for details.

Contributing

Contributions are welcome. Please:

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/improvement)

  3. Add tests for new functionality

  4. Run npm test and cd rust-core && cargo test --release; CI runs both on every pull request

  5. Submit a pull request

Built with Rust and Node.js for the Magento and Adobe Commerce community.

Available Tools

47 tools
magento_analyze_diffA

Analyze git diffs for risk scoring, change classification, and per-file impact analysis. Works on specific commits or staged changes. Useful for code review.

NameRequiredDescriptionDefault
stagedNoSet true to analyze staged changes, false to require commitHash. Default: true.
commitHashNoGit commit hash to analyze. If omitted, analyzes currently staged (git add) changes instead.

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must carry full burden. It describes output behavior (risk scoring, change classification) but does not explicitly state it is read-only or non-destructive, nor cover authentication or rate limits. Lack of annotations makes the description partially adequate but not fully transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no filler. Every clause adds value, clearly conveying purpose and usage.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, so description should clarify return format. It mentions outputs (risk scoring, classification, impact) but lacks detail on how results are presented (e.g., JSON, report). Given the tool's complexity, more completeness would help.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with both parameters described. The description restates 'staged changes or specific commits' which maps directly to the parameters but adds no extra meaning beyond what the schema already provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool analyzes git diffs for risk scoring, change classification, and per-file impact analysis, and specifies it works on commits or staged changes. This distinguishes it well from sibling tools like magento_search or magento_describe.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions 'Useful for code review,' providing context but no explicit when-not-to-use or alternatives. It gives a clear usage scenario without differentiating from siblings like magento_impact_analysis.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_batchA

Execute multiple Magector tool calls in a single request to reduce MCP round-trip overhead. Each query runs in parallel and returns combined results. Use this when you need 2+ independent lookups (e.g., find a class AND its plugins AND its observers in one call instead of three). Supported tools: magento_search, magento_find_class, magento_find_method, magento_find_plugin, magento_find_observer, magento_find_config, magento_find_event_flow, magento_find_di_wiring, magento_find_callers, magento_find_preference, magento_find_fieldset, magento_module_structure, magento_trace_dependency, magento_impact_analysis, magento_grep, magento_read, magento_ast_search, magento_find_dataobject_issues, magento_find_null_risks.

NameRequiredDescriptionDefault
queriesYesArray of tool calls to execute. Each entry has a "tool" name and "args" object.

TDQS

A4.5/5.0
Behavior4/5

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 that queries run in parallel and return combined results, and lists supported tools. It does not detail error handling or rate limits, but the parallelism and batching behavior are clearly disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences, front-loaded with the core purpose. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (batch tool with many sub-tools), the description covers usage context, behavior, and supported operations. Schema covers the parameter, and no output schema is needed for this batching tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 value by explaining the effect of the parameter (parallel execution) and listing the compatible tools, which goes beyond the schema's structural description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: execute multiple Magector tool calls in a single request to reduce round-trip overhead, with parallel execution and combined results. It lists the supported tools, distinguishing it from siblings that operate individually.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use this when you need 2+ independent lookups' and provides examples, giving clear context for when to use. It does not explicitly state when not to use, but the context is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_complexityA

Analyze code complexity — cyclomatic complexity, function count, and line count for PHP files. Identifies complex hotspots and rates each file. Use for refactoring prioritization.

NameRequiredDescriptionDefault
pathNoSpecific file or directory path to analyze instead of a module name
moduleNoMagento module to analyze. Finds all PHP files in the module. Examples: "Magento_Catalog", "Magento_Checkout", "Magento_Sales"
thresholdNoMinimum cyclomatic complexity to report. Set higher (e.g., 10) to only see complex files. Default: 0 (show all)

TDQS

A4.2/5.0
Behavior4/5

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 that the tool analyzes complexity and rates files, implying a read-only operation. No contradictions exist, and for an analysis tool, the behavioral description is adequately transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences, containing no extraneous information. Every word adds value, clearly stating the tool's purpose, metrics, and use case.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, the description covers the key aspects: what it analyzes (complexity metrics), what it produces (hotspots and ratings), and when to use it. The lack of an output schema is partially mitigated by the description of outputs, though a mention of return format would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage with descriptions for all three parameters (path, module, threshold). The description does not add new parameter-specific details beyond the schema, so a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool analyzes code complexity with specific metrics (cyclomatic complexity, function count, line count) for PHP files. It identifies hotspots and rates files, which distinguishes it from sibling tools that focus on searching, finding, or tracing Magento elements.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes a use case ('Use for refactoring prioritization'), providing clear context. However, it does not explicitly state when not to use it or suggest alternatives, though siblings are diverse and no other tool appears to perform complexity analysis.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_describeA

Generate LLM-powered natural language descriptions for di.xml files using Claude Sonnet via the Anthropic API. Requires ANTHROPIC_API_KEY env var. Descriptions are cached and automatically attached to search results for di.xml files.

NameRequiredDescriptionDefault
forceNoForce regeneration of all descriptions, ignoring cached hashes. Default: false.

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description fully carries the behavioral disclosure burden. It discloses API usage, required env var, caching, and automatic attachment to search results—all critical for agent decision-making. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: first states core purpose, second adds critical requirements and side effects. No wasted words; front-loaded with essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity (1 param, no output schema), the description covers purpose, requirements, caching, and integration with search results. It could mention return format, but the absence is acceptable for this tool's scope.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (1 parameter fully described in schema). The tool description does not add extra meaning beyond the schema; it simply restates the purpose. Baseline 3 applies per rubric.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates natural language descriptions for di.xml files using Claude Sonnet via the Anthropic API. This specific verb+resource combination distinguishes it from sibling tools like magento_search or magento_find_class, which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions the prerequisite ANTHROPIC_API_KEY and explains caching behavior, but does not explicitly contrast with alternatives or provide when-to-use/when-not-to-use guidance. The context is clear enough for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_enrichA

Build the method-chain enrichment index. Scans all vendor/ PHP files for two-step method chains (->firstMethod()->secondMethod()) and analyses whether each call has a null guard in surrounding code. Results stored in .magector/data.db. Run this once after magento_index, then use magento_find_null_risks for instant O(1) null-safety queries instead of 20+ grep calls. Also runs automatically after magento_index completes.

NameRequiredDescriptionDefault

No parameters

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavior: it scans PHP files, analyzes method chains, and stores results in .magector/data.db. No hidden side effects 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact yet complete, with every sentence providing essential information about function, usage, and relation to other tools. No fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, 0 parameters, and no output schema, the description fully covers the tool's purpose, input, output, and placement in the workflow. It is self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, so baseline is 4. The description adds no param info, which is appropriate. It mentions the output file location, adding context beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Build' and resource 'the method-chain enrichment index', and distinguishes it from siblings like magento_find_null_risks and magento_index by explaining the dependency and purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to run (once after magento_index), and offers an alternative (use magento_find_null_risks for null-safety queries instead of grep). Also mentions it runs automatically after magento_index.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_error_parserA

Parse a Magento error message or stack trace and map it to relevant source files and root causes. Understands common Magento error patterns: DI instantiation failures, missing class/interface, plugin sort conflicts, area code not set, undefined index in templates, and more. Provides actionable file paths and fix suggestions.

NameRequiredDescriptionDefault
errorYesFull error message, exception message, or stack trace from Magento. Can include PHP fatal errors, uncaught exceptions, or log entries.

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry behavioral disclosure. It states the tool parses errors and provides file paths/fix suggestions, implying read-only behavior. However, it does not clarify what happens with unrecognized error patterns or any side effects, leaving some ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with three sentences: purpose, list of recognized patterns, and output summary. No superfluous content, but the structure could front-load the most critical info (the purpose) more aggressively.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple single-parameter input and no output schema, the description adequately explains what the tool does and what it returns (file paths, fix suggestions). It could be more explicit about the output format, but it is sufficiently complete for an agent to understand its use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single 'error' parameter is fully described in the input schema (100% coverage). The tool description adds no additional semantic value beyond restating what the schema already provides, 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.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as a parser for Magento error messages and stack traces, mapping them to source files and root causes. It lists specific error patterns it handles, distinguishing it from sibling tools that search or find components.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when encountering Magento errors, but does not explicitly state when to prefer this over alternatives like magento_search or magento_grep. No exclusion criteria or prerequisites mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_apiA

Find REST and SOAP API endpoint definitions in webapi.xml and their service class implementations. See also: magento_find_config with configType=webapi, magento_find_class (service class).

NameRequiredDescriptionDefault
queryYesAPI endpoint URL pattern or service method name. Examples: "/V1/products", "/V1/orders", "/V1/carts", "/V1/customers", "/V1/categories", "getList", "save"
methodNoFilter by HTTP method: GET (read), POST (create), PUT (update), DELETE (remove)

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full burden. It correctly identifies the tool as reading definitions and implementations (non-destructive), but does not elaborate on authorization, rate limits, or output behavior. Acceptable but minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences plus a see-also line, entirely front-loaded with the primary purpose. Every sentence serves a purpose with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should clarify what the tool returns (e.g., list of endpoints, struct). It only mentions 'find definitions and implementations' but omits any indication of output format or results count, leaving a significant gap for a tool with simple parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters have descriptive text. The description adds little beyond examples in the query parameter; the schema already conveys the necessary semantics. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Find' and resource 'REST and SOAP API endpoint definitions in webapi.xml and their service class implementations', distinguishing it from siblings like magento_find_config and magento_find_class via explicit cross-references.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides 'See also' pointers to two specific sibling tools (magento_find_config, magento_find_class), giving context on alternatives. It lacks explicit when-not-to-use statements but the see-also effectively guides appropriate tool choice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_blockA

Find Magento Block classes used for view rendering and template logic. Blocks bridge controllers and templates. See also: magento_find_template (PHTML template rendered by the block), magento_find_config with configType=layout.

NameRequiredDescriptionDefault
queryYesBlock class name or functionality description. Examples: "Product\View", "cart totals", "category listing", "customer account navigation", "order view", "Topmenu"

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the purpose and basic role of blocks, but does not mention any behavioral traits like query limitations, rate limits, authentication needs, or side effects. This is inadequate for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with only three sentences, each adding value. It opens with the primary purpose, then adds context, and finally lists related tools. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given one parameter and no output schema, the description should cover what the tool returns or how results are presented. It does not explain the output format or any pagination/ordering. The 'see also' helps contextualize but does not substitute for missing return value details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for the single parameter 'query', including examples. The tool description adds no additional semantic value beyond what the schema already provides. Baseline of 3 is appropriate since schema does the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds Magento Block classes used in view rendering, with a specific verb ('Find') and resource ('Magento Block classes'). It distinguishes from siblings by explicitly mentioning related tools (magento_find_template, magento_find_config) in the 'see also' clause.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context about when to use the tool ('Blocks bridge controllers and templates') and references alternatives (magento_find_template, magento_find_config). However, it does not explicitly state when not to use it or provide exclusion criteria, leaving room for more precise guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_callersA

Find all call sites of a PHP method across the codebase. Searches for ->method() and ::method() patterns in PHP files and method references in XML config files. Use this to understand where a method is used and trace data flow.

NameRequiredDescriptionDefault
classNameNoOptional: class that owns the method — narrows results to files that reference this class. Examples: "SalesRuleManagement", "CartRepository"
methodNameYesMethod name to find callers for. Examples: "execute", "save", "collectTotals", "copySalesRuleIdsFromParentToChildQuote"

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behaviors. It mentions searching in PHP and XML files but omits whether the tool is read-only, any codebase scope limits, or performance considerations. This leaves significant gaps for an AI agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. The first sentence states the core action, the second provides context and patterns. Highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is complex (cross-codebase search), but the description does not explain output format (e.g., list of files with line numbers). Given no output schema, this omission reduces completeness. Parameter documentation is good, but behavioral context is lacking.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers both parameters, and the description adds value by clarifying that className narrows results and providing examples for methodName. It also explains the search patterns (->method(), ::method()), which is beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds all call sites of a PHP method, specifying patterns for PHP and XML. This distinctly sets it apart from siblings that find definitions or other artifacts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says to use it to understand where a method is used and trace data flow, but does not provide explicit when-not-to-use guidance or mention alternatives like magento_trace_call_chain. The guidance is implied but not comprehensive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_classA

Find a PHP class, interface, abstract class, or trait by name in Magento. Locates repositories, models, resource models, blocks, helpers, controllers, API interfaces, and data objects. See also: magento_find_plugin (interceptors for this class), magento_find_preference (DI overrides), magento_find_method (methods in the class).

NameRequiredDescriptionDefault
classNameYesFull or partial PHP class name. Examples: "ProductRepository", "AbstractModel", "CartManagementInterface", "CustomerData", "StockItemRepository"
namespaceNoOptional PHP namespace filter to narrow results. Example: "Magento\Catalog\Model"

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden for behavioral details. It does not disclose whether the operation is read-only, any access restrictions, rate limits, or side effects. The description lacks behavioral context beyond the basic function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded, stating the purpose immediately. It includes examples and sibling references efficiently. However, it could be structured with bullet points for improved readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (2 parameters, no output schema), the description covers key aspects: the types of classes found, example queries, and related tools. It does not explain return format or pagination, but this is acceptable for a search tool with high schema coverage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 example values for className and notes namespace as optional, but does not provide additional semantic meaning beyond what the schema already offers (e.g., no details on partial matching behavior or case sensitivity).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool finds PHP classes, interfaces, abstract classes, or traits by name, and lists concrete examples like repositories, models, and controllers. It also distinguishes from siblings by referencing magento_find_plugin, magento_find_preference, and magento_find_method.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear sibling references with brief explanations of their purposes, guiding when to use alternatives. However, it does not mention when not to use this tool or cover all sibling alternatives (e.g., magento_find_config, magento_find_block).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_configA

Find XML configuration files and nodes in Magento — di.xml (dependency injection), events.xml (observers), routes.xml (routing), system.xml (admin config), webapi.xml (REST/SOAP), module.xml (module declarations), layout XML. See also: magento_find_observer (events.xml), magento_find_preference (di.xml), magento_find_api (webapi.xml).

NameRequiredDescriptionDefault
queryYesWhat configuration to find. Examples: "di.xml preference for ProductRepository", "routes.xml catalog", "system.xml payment field", "events.xml checkout", "layout xml catalog_product_view"
configTypeNoType of XML configuration: di (dependency injection/preferences/virtualTypes), routes (URL routing), system (admin config fields/sections), events (event observers/listeners), webapi (REST/SOAP endpoint definitions), module (module.xml declarations/setup_version), layout (page layout XML/blocks/containers)

TDQS

A3.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavioral traits. It only says 'Find XML configuration files and nodes' but does not mention output format, side effects, permissions, or safety. This lack of transparency for an unannotated tool is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with a short 'See also' line. It is front-loaded with the core purpose and every part serves a function without unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should hint at what the tool returns, but it does not. However, given the low complexity (2 simple params) and the presence of sibling tools for more specific tasks, the description is minimally acceptable but missing return value information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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's examples for the query parameter add some context, but the parameter descriptions in the schema are already detailed. The description does not significantly add new meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds XML configuration files and nodes in Magento, listing specific config types (di.xml, events.xml, etc.). It also distinguishes itself by referencing sibling tools like magento_find_observer for events.xml, showing it is not the only option for those specific tasks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes 'See also: magento_find_observer, magento_find_preference, magento_find_api' which provides explicit guidance on when to use alternative tools for specific config types. This helps an agent choose the correct tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_controllerA

Find MVC controllers by frontend or admin route path. Maps URL routes to Controller action classes with execute() method. See also: magento_find_config with configType=routes.

NameRequiredDescriptionDefault
areaNoMagento area: frontend (storefront routes) or adminhtml (admin panel routes)
routeYesURL route path in frontName/controller/action format. Examples: "catalog/product/view", "checkout/cart/add", "customer/account/login", "sales/order/view", "cms/page/view", "wishlist/index/add"

TDQS

A3.7/5.0
Behavior2/5

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 does not disclose behavioral traits such as read-only nature, error handling (e.g., what happens if route not found), or any side effects. For a tool that is likely read-only, this omission is notable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, with only two sentences and a see-also reference. It is front-loaded with the main purpose and contains no redundant or extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description should mention what the tool returns (e.g., a list of controller classes or paths). It also lacks behavioral details. However, for a simple lookup tool with well-documented parameters, it is minimally adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 both parameters. The description adds context by explaining the mapping to action classes and providing examples, which is helpful but does not significantly surpass the schema's own descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool finds MVC controllers by route path and maps them to action classes. It distinguishes itself from siblings by mentioning a related tool (magento_find_config) with a specific use case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool (finding controllers by frontend/admin route) and references an alternative (magento_find_config) for config routes. However, it lacks explicit when-not or other exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_cronA

Find scheduled cron jobs defined in crontab.xml and their handler classes in Cron/ directories. See also: magento_find_config for crontab.xml raw XML.

NameRequiredDescriptionDefault
jobNameYesCron job name or keyword. Examples: "catalog_product", "indexer", "sitemap", "currency", "newsletter", "reindex", "aggregate", "clean"

TDQS

A3.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose any behavioral traits (e.g., permissions, side effects, or destructive potential). It only describes what the tool finds.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no redundancy; the description is front-loaded with the main action and immediately provides a useful cross-reference.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains the input and general purpose but does not specify output format or behavior (e.g., how results are structured or whether there are pagination/limitations). With no output schema, this is a gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds examples for the jobName parameter (e.g., 'catalog_product', 'indexer'), which helps clarify expected input beyond the schema's brief description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it finds scheduled cron jobs defined in crontab.xml and their handler classes, distinguishing from magento_find_config.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a 'See also' reference to an alternative tool for raw XML, giving context for when to use which tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_dataobject_issuesA

Detect DataObject::setX(null) anti-pattern calls. In Magento, classes extending DataObject store values in a _data array. Calling setX(null) stores the key with a null value — so hasX()/hasData('x') (which use array_key_exists) return true even though the value is null. Downstream guard conditions silently pass, but getX() returns null. The correct way to clear is unsetData('x'). Use this during field-lifecycle audits or when debugging "value persists but shouldn't" bugs. ⚡ For multi-query workflows use magento_batch.

NameRequiredDescriptionDefault
pathNoSubdirectory to search (relative to MAGENTO_ROOT). Default: entire codebase. Example: "vendor/acme/"
maxResultsNoMaximum matches to return (default: 100, max: 500)

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It explains the tool's behavior (detecting setX(null) calls) and the underlying anti-pattern. It does not contradict any annotations since none exist, and it adds useful context about the data array behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is slightly verbose but well-structured, front-loading the core purpose. Every sentence adds value, though some technical detail could be condensed. It remains efficient for agent comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (2 parameters, no output schema), the description explains the anti-pattern and usage but does not describe the output format (e.g., list of matches, code snippets). This leaves a minor gap in what the agent can expect as a result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 both parameters (path and maxResults) adequately. The description does not add significant meaning beyond what is in the schema, which is acceptable given baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool detects DataObject::setX(null) anti-pattern calls in Magento, explaining the problem and why it matters. It distinguishes itself from sibling tools by focusing on this specific anti-pattern.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: during field-lifecycle audits or debugging 'value persists but shouldn't' bugs. It also mentions an alternative sibling tool (magento_batch) for multi-query workflows, though it doesn't explicitly state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_db_schemaA

Find database table definitions, columns, indexes, and constraints declared in db_schema.xml (Magento declarative schema) AND legacy Setup scripts (InstallSchema, UpgradeSchema). Covers both modern declarative schema and legacy $setup->newTable() / addColumn() table definitions. See also: magento_find_trigger (DB triggers), magento_find_table_usage (cross-module table references).

NameRequiredDescriptionDefault
tableNameYesDatabase table name or pattern. Examples: "catalog_product_entity", "sales_order", "customer_entity", "quote", "cms_page", "inventory_source"

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It explains the scope (two sources) but does not disclose behavioral traits such as read-only nature, permission requirements, or return format. It adds some value 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences that front-load the essential purpose and scope, with no extraneous information. Every sentence is useful, and it is appropriately concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low parameter count and no output schema, the description covers the key aspects: what is found and from which sources. It could hint at output format, but the level of detail is adequate for a simple lookup tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage with a clear description and examples for the single parameter. The description does not add additional semantic meaning beyond what the schema provides, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds database table definitions, columns, indexes, and constraints from both modern declarative schema and legacy setup scripts, with a specific verb and resource. It distinguishes from siblings by mentioning magento_find_trigger and magento_find_table_usage.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context (covers both declarative and legacy schema) and mentions related tools in a 'See also' section. However, it does not explicitly state when not to use this tool or list prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_di_wiringA

Get the complete DI wiring picture for a PHP class: preferences (interface→implementation), plugins (interceptors), constructor arguments from di.xml, virtual types, and argument overrides. Also extracts the PHP constructor signature. Use this to understand how a class is configured and extended across all modules.

NameRequiredDescriptionDefault
classNameYesFull or short PHP class/interface name. Examples: "ChildOrderValidatorChain", "Magento\SalesRule\Model\Rule", "CartManagementInterface"

TDQS

A4.2/5.0
Behavior3/5

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 that the tool extracts DI configuration and constructor signatures, but does not mention potential behaviors such as error handling for missing classes, performance implications, or any destructive actions. The description is adequate but not fully transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two efficient sentences. The first sentence lists all retrieved information in a structured bullet-like manner, and the second sentence summarizes the use case. There is no redundant or unnecessary content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a single parameter and no output schema, the description covers the tool's functionality well by listing all return elements. However, it does not describe the structure or format of the output, which could leave the agent uncertain about what to expect. Still, it is generally complete for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema coverage is 100%, giving a baseline of 3. The description adds value by providing concrete examples of valid class name formats (e.g., full or short names) and clarifying that it accepts interfaces. This extra context improves usability beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves the complete DI wiring for a PHP class, listing specific components like preferences, plugins, constructor arguments, virtual types, and argument overrides. This distinct purpose is explicitly differentiated from sibling tools such as magento_find_plugin and magento_find_preference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes the explicit guidance 'Use this to understand how a class is configured and extended across all modules,' which clearly indicates when to use the tool. It does not explicitly mention when not to use it or name alternatives, but the context among sibling tools makes the usage scope clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_event_dispatchersA

Find all PHP locations where a specific Magento event is dispatched via eventManager->dispatch(). Unlike magento_find_event_flow (which shows the full chain: dispatchers+observers+handlers), this tool focuses exclusively on finding WHERE an event is triggered — with exact grep matching, method context, and surrounding code. Use this to answer "does class X dispatch event Y?" or "who triggers this event?".

NameRequiredDescriptionDefault
eventNameYesMagento event name to find dispatchers for. Examples: "sales_order_place_after", "custom_discount_rule_validation_before", "checkout_cart_add_product_complete"

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It states the method (grep matching, method context, surrounding code) and implies read-only operation. However, it does not mention any side effects or auth requirements, but the behavior is straightforward.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (two sentences), front-loaded with the main action, and contains no unnecessary words, efficiently conveying purpose and use.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple parameter (1 required, fully described) and no output schema, the description is nearly complete. It covers purpose, use cases, and technique, though it could explicitly mention the output format (e.g., file paths with code snippets).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides a description with examples for eventName (100% coverage). The description adds context about the tool's purpose and technique but does not significantly enhance the parameter's meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds PHP locations where a Magento event is dispatched via eventManager->dispatch(), and distinguishes itself from the sibling magento_find_event_flow by focusing on the trigger location rather than the full chain.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit use cases are provided: 'does class X dispatch event Y?' and 'who triggers this event?', along with a direct comparison to magento_find_event_flow, guiding the agent on when to use this tool over alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_event_flowA

Trace complete event flow chain: find where an event is dispatched, list all observers registered in events.xml, and resolve observer PHP classes. Shows the full dispatch → observer → handler chain for any Magento event.

NameRequiredDescriptionDefault
eventNameYesMagento event name. Examples: "sales_order_place_after", "checkout_cart_add_product_complete", "catalog_product_save_after", "customer_login", "controller_action_predispatch"

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It describes the analytical steps (trace, find, list, resolve) and implies a read-only analysis, but it does not explicitly state it is non-destructive, list permissions needed, or describe any side effects. It lacks explicit behavioral traits like 'does not modify state'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences with no fluff. The first sentence is action-oriented and front-loaded with the primary action 'Trace complete event flow chain'. Every phrase earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains the tool's purpose and steps adequately. However, since no output schema is provided, it would benefit from specifying the output format (e.g., list, JSON, file paths). The phrase 'Shows the full dispatch → observer → handler chain' is somewhat vague. Slightly more detail on output would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides a description and examples for the single required parameter (eventName). The description does not add any new semantics beyond what the schema states, so it meets the baseline of 3 given 100% schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Trace complete event flow chain' with specific actions (find, list, resolve). It names the resource (event flow, observers, handlers) and distinguishes from siblings like magento_find_event_dispatchers or magento_find_observer by combining multiple steps into a full chain.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide any guidance on when to use this tool versus its siblings. No explicit 'when to use' or 'when not to use' instructions, and no alternatives are mentioned. The user must infer usage from the purpose alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_fieldsetA

Find fieldset.xml definitions that control how data is copied between Magento entities (e.g., order→quote, quote→order). Shows which fields are copied for each aspect (to_order, to_edit, to_quote). Essential for understanding data conversion flows like reorder, order edit, and checkout.

NameRequiredDescriptionDefault
aspectNoAspect name filter. Examples: "to_order", "to_edit", "to_quote", "to_customer"
fieldsetNoFieldset name or partial match. Examples: "sales_copy_order", "sales_convert_quote", "sales_convert_order", "customer_account"

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description reveals the tool shows copied fields per aspect, implying read-only behavior. However, it does not disclose details like permission requirements, case sensitivity, or output format, leaving some behavioral ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action ('Find fieldset.xml definitions') and includes immediate context. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema and is relatively simple, but the description only states it 'shows which fields are copied' without detailing the return structure. Some users may need more clarity on what the tool produces.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers both parameters with descriptions and examples (aspect, fieldset). The tool description adds no extra meaning beyond the schema, so baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds fieldset.xml definitions for data copying between Magento entities, with specific examples like order→quote. It distinguishes from sibling tools by targeting a specific Magento component.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for understanding data conversion flows (reorder, checkout), but does not explicitly state when to use it versus alternatives or when not to use it. Context is clear but lacks comparative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_graphqlA

Find GraphQL schema definitions (.graphqls), types, queries, mutations, and resolver PHP classes. See also: magento_find_class (resolver implementation), magento_find_method (resolver execute method).

NameRequiredDescriptionDefault
queryYesGraphQL type, query, mutation, or interface name. Examples: "products", "createCustomer", "CartItemInterface", "cart", "categoryList", "placeOrder", "createEmptyCart"
schemaTypeNoFilter by GraphQL schema element: type (object types), query (read operations), mutation (write operations), interface (shared contracts), resolver (PHP resolver classes)

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavioral traits. It does not mention whether the tool is read-only, has side effects, requires permissions, or any error conditions. The sole description of 'Find' implies reading, but the agent has no assurance about safety or limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two short sentences with no wasted words. The first sentence delivers the core purpose, and the second efficiently references sibling tools. It is front-loaded and easily scanable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description does not explain what the tool returns (e.g., file paths, code snippets, or structured data). For a search/find tool, this omission leaves the agent without critical information on how to use the results, making it incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already well-described in the schema. The description adds a list of examples for the 'query' parameter and describes the 'schemaType' enum values, but this only marginally extends the schema information. 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.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it finds GraphQL schema definitions (.graphqls), types, queries, mutations, and resolver PHP classes. It provides a specific verb and resource, and the 'See also' note differentiates it from sibling tools like magento_find_class and magento_find_method.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance by pointing to alternative tools (magento_find_class, magento_find_method) for resolver implementation details. This helps an agent decide when to use this tool for GraphQL definitions versus when to use others for PHP code.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_implementorsA

Find all classes that implement a given PHP interface. Scans PHP files for implements keyword and di.xml for <preference> declarations. Use this to discover all concrete implementations of an interface across the codebase.

NameRequiredDescriptionDefault
interfaceNameYesFull or short PHP interface name. Examples: "OrderRepositoryInterface", "Magento\Sales\Api\OrderRepositoryInterface", "ChildOrderValidatorInterface"

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses that scanning covers PHP files for 'implements' and di.xml for '<preference>' declarations, which is good behavioral context. Missing details on performance or error handling are acceptable for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with zero waste. It defines the tool's action first, then provides usage guidance, making it easy to scan and understand quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter search tool with no output schema, the description adequately covers what is searched (PHP files and di.xml) and the method ('implements' keyword and '<preference>' declarations). It could mention return format or limitations but is fairly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the schema already provides excellent parameter documentation (full or short names with examples). The description repeats no additional parameter details, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds all classes implementing a given PHP interface, scanning PHP files and di.xml. It distinguishes from siblings like magento_find_preference and others by specifying the search scope and method.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use this to discover all concrete implementations of an interface across the codebase,' providing clear context. However, it does not explicitly state when not to use or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_layoutA

Find layout XML files — handles, blocks, containers, and referenceBlock/referenceContainer declarations. Parses view//layout/.xml files across all modules. Use to understand page structure and block assignments.

NameRequiredDescriptionDefault
queryNoSearch term to find in layout XML content. Examples: "product.info", "checkout.cart", "minicart", "breadcrumbs", "page.main.title"
handleNoLayout handle name (file name without .xml). Examples: "catalog_product_view", "checkout_index_index", "default", "customer_account"

TDQS

A4/5.0
Behavior3/5

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 describes what the tool does (parses layout XML files) but does not disclose potential behavioral traits like read-only nature, performance impact, or side effects. It adequately implies a read/search operation but lacks explicit safety or scope details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise at two sentences, with no redundant information. The key action and purpose are front-loaded, making it efficient for an AI agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (simple search, no output schema, no annotations), the description provides sufficient context: it covers what files are parsed and the purpose. It could briefly mention the output format or confirm it's read-only, but overall it is nearly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description does not add extra meaning beyond what the schema provides. The schema already includes examples for both parameters ('query' and 'handle'). The description simply restates the purpose without parameter-specific elaboration.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'find' and the specific resources: layout XML files, handles, blocks, containers, and reference declarations. It distinguishes from sibling tools that focus on other Magento components like classes, methods, or config.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear usage context: 'Use to understand page structure and block assignments.' However, it does not explicitly state when not to use this tool or compare it to alternatives among the many sibling tools, which would improve guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_methodA

Find implementations of a PHP method or function across the Magento codebase. Searches method names, function definitions, and class method lists. See also: magento_find_class (parent class), magento_find_plugin (interceptors around this method).

NameRequiredDescriptionDefault
classNameNoOptional class name to narrow method search. Example: "ProductRepository"
methodNameYesPHP method or function name to find. Examples: "execute", "getPrice", "save", "getById", "getList", "beforeSave", "afterDelete", "toHtml", "dispatch"

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It discloses that it searches method names, function definitions, and class method lists, but does not mention behavior on empty results, performance, or output format. Adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three brief sentences, each serving a purpose: what it does, what it searches, and cross-references. Front-loaded and no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the core function but omits return value details and error scenarios. Given no output schema and no annotations, the description is somewhat lacking but still functional for a search tool with clear semantics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The tool description does not add additional parameter semantics beyond what the schema already provides (e.g., examples and descriptions are in schema). No extra value added.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Find implementations of a PHP method or function', clearly specifying the verb 'find' and the resource 'implementations'. It distinguishes from siblings by referencing related tools like magento_find_class and magento_find_plugin.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides 'See also' references to sibling tools for related use cases, but does not explicitly state when to avoid using this tool or describe prerequisites. The context is clear enough for an agent to decide appropriately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_null_risksA

Find method chains without null guards using the pre-built enrichment index. Returns all ->firstMethod()->secondMethod() calls where no null check (=== null, !== null, ?->, ??, isset, is_null) was detected in surrounding code. Requires magento_enrich to have been run first (magento_index triggers it automatically in the background). 100× faster than grep — O(1) SQLite query vs O(n) file scan. Use firstMethod to filter (e.g., "getPayment" finds all ->getPayment()->anything() without null guard). ⚡ For multi-query workflows use magento_batch.

NameRequiredDescriptionDefault
limitNoMaximum results (default: 100, max: 500)
firstMethodNoFilter by first method name. Example: "getPayment" returns all ->getPayment()->$X() without null guard. Omit to get all unsafe chains.

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It explains the tool returns unsafe method chains, requires prior enrichment, and runs a fast SQLite query. Could explicitly state read-only nature, but behavioral traits are well covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence adds value: purpose, dependency, performance, filtering guidance, alternative tool for batch. No wasted words; front-loaded with core functionality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, parameters, dependency, and performance. Lacks explicit return format description, but for a list-returning tool without output schema, the description is sufficiently complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for limit and firstMethod. Description adds concrete examples (e.g., 'getPayment' filters to ->getPayment()->$X() without null guard) and usage context, enhancing understanding beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds method chains without null guards using a pre-built enrichment index. It specifies the exact pattern detected and gives concrete examples, distinguishing it from sibling tools like magento_grep or magento_find_class.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states dependency on prior enrichment (magento_enrich or magento_index), provides filtering guidance via firstMethod parameter, notes performance advantage, and suggests magento_batch for multi-query workflows.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_observerA

Find event observers (listeners) for a Magento event. Locates Observer classes and events.xml declarations. See also: magento_find_config with configType=events for raw XML.

NameRequiredDescriptionDefault
eventNameYesMagento event name. Examples: "checkout_cart_add_product_complete", "sales_order_place_after", "catalog_product_save_after", "customer_login", "controller_action_predispatch"

TDQS

A3.7/5.0
Behavior2/5

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 describes what it finds but does not disclose behavioral traits like side effects, performance, or output format. As a read-only lookup tool, minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very concise: two sentences with front-loaded action. No wasted words, efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a single required parameter and no output schema, the description covers purpose and sibling hint. However, it does not hint at the output format (e.g., list of classes), which would improve completeness for a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with examples. The description adds no additional parameter semantics beyond what the schema provides, 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.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds event observers and locates Observer classes and events.xml declarations. It distinguishes from sibling magento_find_config by mentioning an alternative use case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a 'See also' reference to magento_find_config for raw XML, offering guidance on when to use an alternative. Does not explicitly state when not to use this tool, but sufficient for a single-purpose tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_pluginA

Find Magento plugins (interceptors) that modify class behavior via before/after/around methods. Locates Plugin classes and di.xml interceptor declarations. See also: magento_find_class (target class details), magento_find_method (intercepted method), magento_find_config with configType=di.

NameRequiredDescriptionDefault
targetClassNoClass being intercepted by plugins. Examples: "ProductRepository", "CartManagement", "CustomerRepository", "OrderRepository", "Topmenu"
targetMethodNoSpecific method being intercepted. Examples: "save", "getList", "getById", "getHtml", "dispatch"

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It only states the basic purpose (find plugins) without describing what the output looks like, whether it returns detailed info, or any side effects. This is insufficient for full transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (2 sentences) with no wasted words. It front-loads the purpose and packs in relevant cross-references, though a sentence on output could be added without bloating.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a find tool with 2 optional parameters and no output schema, the description adequately explains what it does and guides to related tools. It lacks details on return format or limitations, but is generally complete for the use case.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 both parameters. The description adds examples but no additional meaning beyond the schema, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds Magento plugins (interceptors) that modify class behavior via before/after/around methods, and locates Plugin classes and di.xml declarations. It effectively distinguishes from sibling tools by referencing related tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit links to alternative tools (magento_find_class, magento_find_method, magento_find_config) with usage hints, but does not explicitly state when not to use this tool or describe prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_preferenceA

Find DI preference overrides — which concrete class implements an interface or replaces another class via di.xml. See also: magento_find_class (implementation details), magento_find_config with configType=di.

NameRequiredDescriptionDefault
interfaceNameYesInterface or class name to find preference/implementation for. Examples: "ProductRepositoryInterface", "StoreManagerInterface", "LoggerInterface", "OrderRepositoryInterface", "CustomerRepositoryInterface"

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It states it finds preference overrides from di.xml, implying a read-only search. But does not disclose any permissions requirements or potential side effects. Adequate but not fully transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. Front-loaded with core function, then pointers to related tools.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given single parameter, no output schema, and no annotations, description adequately covers purpose and context. However, lacks detail on output format or edge cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with examples. Description adds context that the parameter is used to find preference/implementation, supplementing the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb+resource: 'Find DI preference overrides'. Specifies purpose: which concrete class implements an interface or replaces another class via di.xml. Distinguishes from sibling tools by mentioning magento_find_class and magento_find_config.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly references sibling tools (magento_find_class, magento_find_config) with context on when to use them. However, does not explicitly state when to use this tool vs alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_table_usageA

Find all code that references a database table — across db_schema.xml, Setup scripts (InstallSchema/UpgradeSchema), raw SQL (Zend_Db_Expr, $connection->query), getTable() calls, and resource model definitions. Builds a cross-module dependency map showing who reads/writes/creates a given table. Essential for impact analysis of schema changes.

NameRequiredDescriptionDefault
tableNameYesDatabase table name to find all references for. Examples: "salesrule_ordered", "catalog_product_entity", "quote_item"

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It discloses the types of code searched and the output format (dependency map). It does not mention whether the tool is read-only or any destructive side effects, but the description implies a read-only analysis. The lack of explicit read-only statement prevents a score of 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, using two sentences plus parameter description. It front-loads the purpose and lists specific code types efficiently. It could be slightly tighter, but there is no excessive verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (scanning multiple Magento code artifacts), the description covers the input (table name) and output (dependency map) well. No output schema exists, but the description hints at the return format. Without annotations, this is reasonably complete, though it could mention prerequisites like having a Magento codebase indexed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides a description for the single parameter tableName, achieving 100% schema coverage. The tool description adds example values (e.g., 'salesrule_ordered'), which are helpful but not essential. Since schema already covers the parameter meaning, the description adds marginal value, warranting a baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Find all code that references a database table' and specifies the exact types of code scanned (db_schema.xml, Setup scripts, raw SQL, etc.). It also explains the outcome: 'Builds a cross-module dependency map showing who reads/writes/creates a given table.' This distinguishes it from sibling tools like magento_find_db_schema, which focuses on schema definitions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says 'Essential for impact analysis of schema changes,' which implies usage context but does not explicitly say when to use this tool versus alternatives such as magento_find_db_schema or magento_trace_dependency. No exclusion criteria or when-not-to-use guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_templateA

Find PHTML template files in Magento for frontend or admin rendering. Locates view templates for product pages, checkout, customer account, cart, CMS, catalog listing, and more. See also: magento_find_block (Block class rendering the template).

NameRequiredDescriptionDefault
areaNoMagento area: frontend (customer-facing storefront), adminhtml (admin panel), base (shared/fallback)
queryYesTemplate description or filename pattern. Examples: "product listing", "checkout form", "customer account dashboard", "minicart", "breadcrumbs", "category view", "order summary"

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must cover behavioral traits. It only states the tool finds templates without mentioning side effects, performance, or result format. This is a gap for a read-like operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences plus a 'See also' reference, with the main action front-loaded. Every sentence contributes value, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description provides examples and areas but does not explain return values or response structure. With no output schema, this is a gap. However, given the tool's simplicity and the schema coverage, it is minimally adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema; it lists example queries but those are also in the schema's description. No extra semantic clarification.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds PHTML template files in Magento for frontend or admin rendering, with specific examples (product pages, checkout, etc.). It distinguishes from sibling magento_find_block by noting the block class rendering the template.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a 'See also' reference to magento_find_block, suggesting a related tool, but lacks explicit when-to-use or when-not-to-use instructions. The context is clear enough for an experienced Magento developer but could be more specific.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_testA

Find PHPUnit test files for a given PHP class or method. Searches Test/ directories for test classes, @covers annotations, mock references, and class name matches. Helps identify test coverage for refactoring.

NameRequiredDescriptionDefault
classNameYesPHP class name to find tests for. Examples: "ProductRepository", "CartManagement", "OrderService"
methodNameNoOptional method name to narrow test search. Examples: "save", "getById", "execute"

TDQS

A3.8/5.0
Behavior3/5

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 explains search methods (Test/ directories, @covers, mocks, class names) but does not disclose whether the tool is read-only, requires authentication, or has rate limits. The behavior is implied to be safe and non-destructive, but not explicitly stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences: purpose, method, benefit. No extraneous words, front-loaded with the primary action. Highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool, the description covers purpose, search method, and use case. No output schema exists, but return format (test file paths) is implicit. Adequate for typical usage, though could mention result structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema coverage is 100%, with each parameter description including examples. The tool description adds no additional parameter semantics beyond what the schema provides. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds PHPUnit test files for a given PHP class or method, specifying verb, resource, and context. It distinguishes from sibling tools (e.g., magento_find_class, magento_find_method) by focusing specifically on test identification.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage during refactoring ('helps identify test coverage') but does not provide explicit guidance on when to use versus alternatives, nor does it mention when not to use. Sibling tools are listed but not referenced for exclusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_find_triggerA

Find MySQL database trigger definitions in Magento Setup scripts. Detects triggers created via TriggerFactory (setName, setTable, setEvent, setTime, addStatement, createTrigger). Returns trigger name, target table, event type (INSERT/UPDATE/DELETE), timing (BEFORE/AFTER), and SQL statements. Use when investigating DB-level automation, trigger chains, or performance issues caused by cascading triggers.

NameRequiredDescriptionDefault
tableNameNoOptional table name to find triggers targeting this table.
triggerNameNoOptional trigger name or pattern to search for. If omitted, finds all triggers in the codebase.

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses that the tool detects triggers created via specific methods and returns relevant details. It suggests a read-only nature (detecting/finding) with no side effects mentioned. Could be more explicit about safety, but sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (3-4 sentences) and front-loaded with the main purpose. Every sentence adds information without redundancy. Structure is clear and scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a find tool with no output schema, the description adequately explains what it does, how it works, and what it returns. It could mention examples or error handling, but overall it is complete enough for an AI agent to decide whether to use it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for both optional parameters. The description adds value by explaining the purpose of each parameter and what the tool returns, complementing the schema effectively.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it finds MySQL database trigger definitions in Magento Setup scripts, specifically those created via TriggerFactory methods. It lists the returned fields (name, table, event, timing, SQL) and distinguishes itself from sibling tools by focusing on triggers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit usage context: 'Use when investigating DB-level automation, trigger chains, or performance issues caused by cascading triggers.' Does not explicitly mention when not to use or alternatives, but the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_grepA

Exact text search (grep) across Magento PHP/XML/JS files. Unlike magento_search (semantic/vector), this finds EVERY occurrence of a literal string or regex pattern. Use for: finding all call sites of a method, all usages of a class name, all config references. Returns file:line:content for each match.

NameRequiredDescriptionDefault
pathNoSubdirectory to search in (relative to MAGENTO_ROOT). Default: "." (entire codebase). Examples: "vendor/acme/", "app/code/", "vendor/magento/module-sales/"
contextNoLines of context around each match (default: 4). Like grep -C. Use 0 for broad scans with many matches, then batch-read specific files.
includeNoFile glob pattern to include. Default: "*.php". Examples: "*.xml", "*.{php,xml}", "*.js", "*.phtml"*.php
patternYesText pattern to search for. Literal string or POSIX regex. Examples: "getPayment()->getMethod()", "removeButton", "sales_order_place_after", "class AddressConditions"
filesOnlyNoReturn only file paths (like grep -l). No content, no context. Use for discovery: first find which files match, then batch-read them with magento_read. Dramatically reduces tokens when pattern matches many files.
ignoreCaseNoCase-insensitive search (default: false)
maxResultsNoMaximum number of matches to return (default: 50, max: 200)

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It explains the grep-like behavior, return format (file:line:content), and notes it finds EVERY occurrence. No contradictions; adds sufficient transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, front-loaded with purpose, no wasted words. Efficiently conveys core function, use cases, and output format.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description includes return format and comprehensive use cases. For a grep tool with well-documented parameters, this is fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 value by providing usage tips (e.g., use 0 context for broad scans, then batch-read) and clarifies default behaviors. Slightly above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states exact text search (grep) across Magento files, contrasts with semantic search (magento_search), and provides specific use cases (finding call sites, usages, config references). Distinguishes from siblings effectively.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly lists use cases and contrasts with magento_search. Does not mention when not to use or direct alternatives for other siblings, but the context is clear enough for an agent to decide.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_impact_analysisA

Analyze the impact of changing a PHP class — finds all files that reference it via use statements, DI configuration, instantiation, and type hints. Combines DI XML tracing with PHP source analysis to map cross-module dependencies.

NameRequiredDescriptionDefault
classNameYesFull or partial PHP class/interface name. Examples: "ProductRepository", "CartManagementInterface", "StoreManagerInterface"

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses that the tool combines DI XML tracing with PHP source analysis and maps cross-module dependencies. This gives insight into the operational behavior, though it does not mention auth needs or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two concise sentences. The first sentence immediately conveys the core action and scope, and the second adds methodological detail. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has one parameter, full schema coverage, and no output schema, the description provides sufficient context. It explains what the tool does and how, but does not describe the output format, which would be helpful for completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% coverage for the single 'className' parameter. The description adds value by specifying that the parameter can be a full or partial name and provides concrete examples, enhancing the schema's plain string type description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool analyzes the impact of changing a PHP class by finding all files that reference it via use statements, DI configuration, instantiation, and type hints. It specifies the resource (PHP class) and action (analyze impact), distinguishing it from sibling tools like magento_find_class or magento_trace_dependency.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: when you need to understand the impact of changing a class. It does not explicitly exclude scenarios or mention alternatives, but the context is clear enough for an agent to infer appropriate use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_indexA

Index or re-index the Magento codebase for semantic search. Run this after code changes to update the search index. Indexes PHP, XML, JS, PHTML, and GraphQL files.

NameRequiredDescriptionDefault
pathNoAbsolute path to Magento 2 root directory. Uses configured MAGENTO_ROOT if not specified.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must bear full responsibility. It states the tool indexes/re-indexes and lists file types, but lacks disclosure of potential performance impact, resource consumption, or failure modes. For a potentially heavy operation, more transparency would be beneficial.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose, and every sentence adds value. There is no fluff, making it highly concise and structured well for an AI agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one optional parameter and no output schema, the description covers the key aspects: purpose, when to use, and scope (file types). It could mention whether the operation is incremental or full, and what feedback to expect, but it is largely complete given the complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already fully describes the single optional parameter 'path' with a clear description. The tool description does not add any additional semantic meaning beyond what the schema provides, 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.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool indexes or re-indexes the Magento codebase for semantic search, specifies when to run it (after code changes), and lists the file types it indexes. This differentiates it from the many sibling search/find tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises to run this tool after code changes to update the search index, providing clear usage context. However, it does not mention when not to use it or explicitly contrast with alternatives, though the context of sibling tools implies it is a prerequisite for searches.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_module_structureA

Get the complete structure of a Magento module — lists all controllers, models, blocks, plugins, observers, API classes, XML configs, and templates. Provides an overview of module architecture.

NameRequiredDescriptionDefault
moduleNameYesFull Magento module name in Vendor_Module format. Examples: "Magento_Catalog", "Magento_Sales", "Magento_Customer", "Magento_Checkout", "Vendor_CustomModule"

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It lists what the tool returns (component types) but does not disclose behavioral traits like whether it requires a working Magento installation, performance considerations, or any side effects. The description is adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with front-loaded action verb 'Get'. Every sentence adds value with no wasted words. Information is presented efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema, the description lists many component types, providing a good overview. It could be more explicit about the output format (e.g., list vs. hierarchy) but is sufficiently complete for a structural overview tool among many specific siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with clear examples for the parameter. The tool description adds no additional meaning beyond what the schema already provides, achieving the baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets the complete structure of a Magento module and enumerates component types (controllers, models, etc.). This specific verb+resource distinguishes it from sibling tools that focus on individual components.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for obtaining an overall module architecture overview but does not explicitly state when to use this tool versus alternatives like magento_find_controller. No when-not or exclusion criteria are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_performance_profileA

Profile a Magento subsystem for performance bottlenecks. Scans for all plugins, observers, and collectors registered on a critical path (e.g., checkout totals, order placement, product save). Returns files sorted by complexity score to identify likely performance hotspots.

NameRequiredDescriptionDefault
subsystemYesMagento subsystem to profile. Examples: "checkout_totals", "order_place", "product_save", "cart_add", "customer_login", "catalog_reindex"
thresholdNoMinimum complexity score to include in results (default: 0). Set higher (e.g., 5) to focus on complex files only.

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It explains that the tool scans for components and returns sorted files, but does not explicitly state whether it is read-only, if it modifies data, or any authentication needs. This leaves some ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized with two sentences. The first sentence front-loads the core action, and the second provides additional detail. Every sentence serves a purpose without redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema, so the description should explain return values. It states returns files sorted by complexity score, but lacks details on the exact format or how to interpret results. Given the low parameter count and clear purpose, it is mostly complete but has minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with both parameters described. The description adds value beyond the schema by providing an example for the threshold parameter ('Set higher (e.g., 5) to focus on complex files only'), which helps agents use it effectively.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool profiles a Magento subsystem for performance bottlenecks, specifying scanning for plugins, observers, and collectors. It distinguishes itself from sibling tools like magento_find_plugin by focusing on performance hotspot identification rather than individual element lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly indicates when to use the tool (to identify performance bottlenecks) but does not explicitly mention when not to use it or suggest alternatives. The context is clear, but lacking exclusions prevents a higher score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_readA

Read a file from the Magento codebase. Use in magento_batch to read multiple files in a single MCP call (e.g., grep finds 5 files → read all 5 in one batch). Supports line ranges and method extraction.

NameRequiredDescriptionDefault
pathYesFile path relative to MAGENTO_ROOT. Example: "vendor/acme/module-sales/Model/OrderService.php"
endLineNoStop reading at this line number (inclusive). Default: end of file. Use with startLine for large files.
startLineNoStart reading from this line number (1-based). Default: 1 (beginning of file).
methodNameNoExtract only this method from the file (uses brace-counting). Returns the complete method body with line numbers. Much more token-efficient than reading the whole file. Example: "execute"

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Mentions token-efficiency of method extraction but does not disclose read-only nature, auth needs, or output format. Adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences that front-load purpose and provide actionable usage guidance without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers main functionality, batching, line ranges, and method extraction. Lacks output format details and error handling, but sufficient for a simple read tool given parameter richness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers all parameters with descriptions. Description adds value with example, batching context, and token-efficiency hint, enhancing understanding beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool reads a file from the Magento codebase. Distinguishes from siblings by mentioning integration with magento_batch for batch reading.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on using magento_batch for multiple files and mentions line ranges and method extraction. Could be improved by clarifying when not to use vs specific sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_statsA

Get index statistics — total indexed vectors, embedding dimensions, and database path. Use this to verify the index is loaded and check its size.

NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully carries behavioral disclosure. It lists the output fields (vectors, dimensions, path), implying a read-only operation. No side effects or destructive actions are indicated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first states purpose, second adds usage guidance. No unnecessary words; every sentence is valuable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers output and usage adequately for a simple parameterless tool. Could mention prerequisites (e.g., index must exist) but sufficient overall.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so no parameter documentation is needed. Schema coverage is 100% trivially. Baseline 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves index statistics (total indexed vectors, embedding dimensions, database path). This distinguishes it from siblings like magento_search (searching) or magento_index (managing index).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says 'Use this to verify the index is loaded and check its size,' providing clear context for when to use. However, it does not mention alternatives 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.

magento_trace_apiA

Trace a REST or GraphQL API endpoint from URL to implementation. Parses webapi.xml to find the service interface, resolves the DI preference to the concrete class, reads the execute/method body, and checks di.xml for constructor arguments. Returns the complete chain in one call.

NameRequiredDescriptionDefault
urlNoREST API URL pattern to trace. Example: "/V1/orders/:orderId/items", "/V1/carts/mine/payment-information"
methodNoHTTP method (GET, PUT, POST, DELETE). Default: any.
interfaceNameNoAlternative: service interface class name. Example: "ChangePaymentMethodInterface"

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the key behavioral steps (parsing webapi.xml, resolving DI, reading method, checking di.xml) and states it returns the complete chain in one call. It does not mention any destructive actions, which is appropriate for a trace tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph of three sentences, front-loading the purpose and listing steps without redundancy. Every sentence adds essential information, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains the core behavior and output ('complete chain in one call') without an output schema. It covers the tool's functionality for three optional parameters. Minor gaps: no mention of error handling or response format, but adequate for a trace tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are documented. The description adds value by explaining the purpose of the 'url' parameter with examples, clarifying the 'method' enum as HTTP methods, and noting 'interfaceName' as an alternative. However, it could better clarify GraphQL usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool traces a REST or GraphQL API endpoint from URL to implementation, detailing the specific steps (parse webapi.xml, resolve DI preference, etc.). It distinguishes itself from sibling tools like magento_find_api by focusing on the full implementation chain.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for tracing API endpoints to their implementation, but it does not explicitly state when to use this tool over alternatives (e.g., magento_trace_flow). The context of sibling tools hints at its distinct purpose, but explicit guidance is missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_trace_call_chainA

Trace the internal method call chain starting from a specific class::method. Follows $this->method() calls (same class), $this->dependency->method() calls (resolves DI types), and eventManager->dispatch() calls (maps to observers from events.xml). Returns a call tree showing the execution path through the code.

NameRequiredDescriptionDefault
maxDepthNoMaximum recursion depth for tracing (default: 3). Higher values trace deeper but take longer.
classNameYesFull PHP class name (FQCN) to start tracing from. Examples: "Vendor\OrderSplit\Model\CreateOrder\CreateChildOrder", "Magento\Quote\Model\QuoteManagement"
methodNameYesMethod name to start tracing. Examples: "execute", "submit", "collectTotals"

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses what types of calls are traced and that a call tree is returned. It does not mention limitations (e.g., dynamic calls) but is reasonably transparent for a static analysis tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, each adding value: first states purpose and scope, second details what is traced and return type. No wasted words, front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the tool's purpose, inputs, and behavior. It lacks details on the output format (call tree structure), but for a simple tracing tool with 3 parameters, it is fairly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All three parameters are well-described in the schema with examples for className and methodName, and maxDepth has default and description. The description adds no additional param info, but schema coverage is 100%. Examples add value, so above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it traces the internal method call chain from a specific class::method, detailing types of calls followed (same class, DI, events). This distinguishes it from siblings like magento_find_callers or magento_trace_flow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool (tracing execution path from a method), but does not explicitly exclude alternatives or mention when not to use it. It implicitly differentiates from sibling tools through specificity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_trace_configA

Trace a Magento config path end-to-end: finds system.xml admin definition (label, type, source_model), PHP classes that read the value, and actual DB values from config-data exports. Use when investigating config-driven behavior ("why is this feature enabled/disabled?", "what controls marketplace payment methods?"). Accepts either an exact config path or a keyword to search for. IMPORTANT: If the output says no config-data exports are available, or if the analysis needs config values from a country/environment not yet exported, ask the user to provide the export. They can run a one-time MySQL query and place the JSON file in .magector/config-data/{country}-{environment}.json.

NameRequiredDescriptionDefault
keywordNoKeyword to search for in system.xml fields when exact path is unknown. Example: "marketplace_payment", "cashondelivery". Returns all matching config paths.
configPathNoExact config path to trace. Example: "acme_marketplace/payments/marketplace_payment_methods", "payment/cashondelivery/active"

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavioral traits. The description lacks any mention of whether the tool modifies data, requires authentication, or has rate limits. It only describes what information it retrieves, without addressing side effects or prerequisites beyond the export requirement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is 4 sentences, with the purpose front-loaded in the first sentence. Every sentence adds value: purpose, usage context, input clarifications, and an important note. No redundant words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema, and the description does not explain the structure or format of the output beyond listing what it finds. The IMPORTANT note hints at possible missing data, but for a comprehensive understanding, more detail about the output would be beneficial. It is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so the baseline is 3. The description adds the context that the tool accepts either an exact path or keyword, but this is already stated in the schema parameter descriptions. No additional semantic meaning is provided beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool traces a Magento config path end-to-end, specifying exactly what it finds: system.xml definition, PHP classes, and DB values. The verb 'trace' and resource 'config path' are specific, and it differentiates from sibling tools like magento_find_config by emphasizing the end-to-end tracing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use the tool: 'when investigating config-driven behavior' with examples. It also includes an IMPORTANT note guiding the agent on what to do if exports are missing. It does not explicitly mention when not to use or alternatives, but the guidance is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_trace_data_flowA

Trace how a data attribute flows through the Magento codebase: find all PHP files that set (via magic setter, setData, addData) and get (via magic getter, getData) a specific attribute key. Shows which classes write vs read the attribute, in which methods, and whether XML configs reference it. Use this to understand data dependencies — e.g., who sets custom_discounted_price_incl_tax on Quote\Address and who reads it.

NameRequiredDescriptionDefault
modelClassNoOptional: model class name to prioritize results that reference this class. Examples: "Quote\Address", "Order", "Product"
attributeKeyYesThe snake_case data attribute key to trace. Examples: "custom_discounted_price_incl_tax", "base_grand_total", "custom_free_shipping_price", "subtotal_with_discount"

TDQS

A4.2/5.0
Behavior3/5

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 explains the tool's output (set/get files, XML references) and implies read-only analysis, but does not explicitly disclose safety, side effects, or rate limits. The description adds moderate context beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loaded with the core purpose, and includes an example. No redundant or missing information; every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 2 parameters and no output schema, the description adequately explains what the tool does and what output to expect (PHP files, set/get, XML configs). It's fairly complete but could specify search scope (e.g., recursive or limited to certain directories).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for both parameters. The description adds meaningful context by showing how to use the parameters in a real scenario ('who sets custom_discounted_price_incl_tax on Quote\Address'). This goes beyond just describing the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Trace how a data attribute flows through the Magento codebase' with specific verbs ('trace', 'find') and resources ('PHP files', 'XML configs'). It distinguishes from siblings by focusing on data attribute flow, with a concrete example (custom_discounted_price_incl_tax on Quote\Address).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear use case ('Use this to understand data dependencies...') and an example. However, it does not explicitly state when not to use this tool or compare it to sibling trace tools like magento_trace_flow or magento_trace_call_chain, leaving some ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_trace_dependencyA

Trace dependency injection graph for a PHP class or interface. Parses di.xml files across all modules to find: preferences (interface→implementation), plugins (interceptors), virtualTypes, and constructor argument overrides. Use this to understand how Magento resolves a class at runtime — especially useful for "Cannot instantiate interface" errors.

NameRequiredDescriptionDefault
classNameYesFull or partial PHP class/interface name to trace. Examples: "ProductRepositoryInterface", "CartManagementInterface", "LoggerInterface", "StoreManagerInterface"
directionNo"resolve" finds what implements/replaces this class (preferences, virtualTypes). "dependents" finds what depends on this class (plugins, type arguments). "both" does both. Default: both.both

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavior. It states it parses di.xml files across modules and lists what it finds, but does not discuss potential performance impacts, read-only nature, or output size. This 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: three sentences front-loading the purpose, technical details, and a practical use case. Every sentence adds value with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description omits any mention of return format or structure. For a tool that traces dependencies, knowing what the output looks like (e.g., a dependency graph or list) would help an agent interpret results. This is a moderate gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions, but the description adds valuable examples for className and explains the direction enum options. This enhances understanding beyond schema alone, earning a score above the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: tracing dependency injection graphs for PHP classes/interfaces in Magento. It specifies actions (parsing di.xml, finding preferences, plugins, etc.) and a concrete use case ('Cannot instantiate interface' errors), distinguishing it from sibling find tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly recommends use for understanding runtime class resolution, especially for specific errors. While it does not list alternatives or exclusions, the context of sibling tools implies uniqueness, and the guidance is clear enough for an AI agent to decide when to invoke this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_trace_flowA

Trace Magento execution flow from an entry point (route, API endpoint, GraphQL mutation, event, or cron job). Chains multiple searches to map controller → plugins → observers → templates for a given request path. Use this to understand how a request is processed end-to-end.

NameRequiredDescriptionDefault
depthNoTrace depth. "shallow" traces entry point + config + direct plugins (faster). "deep" adds observers, layout, templates, and DI preferences (more complete). Default: shallow.shallow
entryTypeNoType of entry point. "auto" detects from the pattern (default). Override when auto-detection is wrong.auto
entryPointYesThe entry point to trace. Examples: "checkout/cart/add" (route), "/V1/products" (API), "placeOrder" (GraphQL), "sales_order_place_after" (event), "catalog_product_reindex" (cron)

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It discloses chaining multiple searches to map controller to plugins to observers to templates, and mentions depth and entryType controls. Good disclosure of behavior, though no mention of side effects or limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. First sentence immediately states purpose and examples. Second sentence explains what it does (chains searches) and use case. Front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and lack of output schema, the description adequately explains what it traces and how. It covers entry types and depth. Could mention return format (a trace map) but not critical. Good overall.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with clear parameter descriptions. The description adds marginal value beyond schema (e.g., 'faster' vs 'more complete' for depth), but this is baseline 3 as schema already documents parameters well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'trace' and resource 'Magento execution flow', listing multiple entry point types (route, API, GraphQL, event, cron). This clearly distinguishes it from sibling tools like magento_search or magento_find_class.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states 'Use this to understand how a request is processed end-to-end.' While it doesn't list when-not-to-use or alternatives, the sibling context implies specialized tools exist for sub-steps, making usage clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

magento_trace_shipping_chainA

Trace the complete shipping rate calculation chain: carrier classes → plugins on collectRates() → ShippingRateModifier pool → totals collectors → fieldset copy mappings. Use this to understand how shipping prices are calculated, modified, and propagated during checkout, reorder, or order edit.

NameRequiredDescriptionDefault
carrierNoOptional carrier or shipping method to focus on. Examples: "flatrate", "freeshipping", "tablerate", "innoship", "home_delivery", "pickup"

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must cover behavioral traits. It describes what the tool traces but does not disclose rate limits, side effects, or read-only nature. Adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with actionable information. No redundancy, every word serves purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but description does not explain return format (e.g., list of steps, code). For a tracing tool, more detail on output would be beneficial. Adequate given simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear description and examples for 'carrier'. Description does not add meaning beyond schema, scoring baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description starts with specific verb 'Trace' and enumerates the chain components (carrier classes, plugins, modifier pool, collectors, fieldset mappings), clearly differentiating from sibling tracing tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states use cases: 'understand how shipping prices are calculated, modified, and propagated during checkout, reorder, or order edit.' Does not mention when not to use or compare to siblings, but context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 47 tool updatesv2.16.16
    • First observedmagento_analyze_diff
    • First observedmagento_ast_search
    • First observedmagento_batch
    • First observedmagento_complexity
    • First observedmagento_describe
    • First observedmagento_enrich
    • First observedmagento_error_parser
    • First observedmagento_find_api
    • First observedmagento_find_block
    • First observedmagento_find_callers
    • First observedmagento_find_class
    • First observedmagento_find_config
    • First observedmagento_find_controller
    • First observedmagento_find_cron
    • First observedmagento_find_dataobject_issues
    • First observedmagento_find_db_schema
    • First observedmagento_find_di_wiring
    • First observedmagento_find_event_dispatchers
    • First observedmagento_find_event_flow
    • First observedmagento_find_fieldset
    • First observedmagento_find_graphql
    • First observedmagento_find_implementors
    • First observedmagento_find_layout
    • First observedmagento_find_method
    • First observedmagento_find_null_risks
    • First observedmagento_find_observer
    • First observedmagento_find_plugin
    • First observedmagento_find_preference
    • First observedmagento_find_table_usage
    • First observedmagento_find_template
    • First observedmagento_find_test
    • First observedmagento_find_trigger
    • First observedmagento_grep
    • First observedmagento_impact_analysis
    • First observedmagento_index
    • First observedmagento_module_structure
    • First observedmagento_performance_profile
    • First observedmagento_read
    • First observedmagento_search
    • First observedmagento_stats
    • First observedmagento_trace_api
    • First observedmagento_trace_call_chain
    • First observedmagento_trace_config
    • First observedmagento_trace_data_flow
    • First observedmagento_trace_dependency
    • First observedmagento_trace_flow
    • First observedmagento_trace_shipping_chain
Deploy Server
Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

TDQS

A4/5.0

Scored across 47 tools

Disambiguation5/5

Each tool has a clearly distinct purpose, with descriptions that cross-reference related tools, minimizing ambiguity. Even overlapping functions like semantic search vs. grep are well-delineated.

Naming Consistency4/5

All tools follow the 'magento_<verb>_<noun>' pattern with snake_case, though a few (e.g., magento_module_structure, magento_complexity) deviate slightly. Overall, naming is predictable and consistent.

Tool Count3/5

47 tools is on the high end, covering a broad domain. While each tool is justified, the large number may overwhelm agents, requiring careful selection.

Completeness5/5

The tool set covers virtually every aspect of Magento codebase analysis: search, discovery, tracing, debugging, performance, and batch operations. No significant gaps are apparent.

Maintenance

ActivityActive
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers

  • SRC (Structured Repo Context)

    kvnpetit
    A
    license
    A
    quality
    A
    maintenance
    An MCP server and CLI tool that transforms codebases into AI-ready context through semantic search, call graph analysis, and incremental indexing. It enables AI assistants to perform hybrid vector and keyword searches to understand complex repository structures and cross-file relationships.
    35
    59 npm
    1
    MIT

  • Axon.MCP.Server

    ali-kamali
    F
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that transforms codebases into intelligent, queryable knowledge bases, enabling AI assistants to perform semantic search, explore architecture, and analyze code relationships.
    166
    -

  • codebaxing

    duysolo
    A
    license
    A
    quality
    D
    maintenance
    MCP server for semantic code search that indexes your codebase and allows AI editors to search using natural language queries.
    9
    12 npm
    53
    MIT