How do I use Magector?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Magector how are checkout totals calculated?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Magector

by krejcif

Overview Schema Related Servers Score Discussions

JavaScript

Local

Magector

Technology-aware MCP server for Magento 2 and Adobe Commerce with intelligent indexing and search.

Magector is a Model Context Protocol (MCP) server that deeply understands Magento 2 and Adobe Commerce. It builds a semantic vector index of your entire codebase — 18,000+ files across hundreds of modules — and exposes 47 tools that let AI assistants search, navigate, and understand the code with domain-specific intelligence. Instead of grepping for keywords, your AI asks "how are checkout totals calculated?" and gets ranked, relevant results in under 50ms, enriched with Magento pattern detection (plugins, observers, controllers, DI preferences, layout XML, and 20+ more).

Rust Node.js Magento Adobe Commerce Accuracy License: MIT

Why Magector

Magento 2 and Adobe Commerce have 18,000+ 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. No single file tells the full story.

Generic search tools — grep, IDE search, or the keyword matching built into AI assistants — can't bridge this gap. They find literal strings but can't connect "how does checkout calculate totals?" to TotalsCollector.php when the word "totals" appears in hundreds of unrelated files.

Magector solves this with three layers of intelligence:

Semantic vector index — every file is embedded into a 384-dimensional space (ONNX, all-MiniLM-L6-v2) where meaning matters more than keywords. A search for "payment capture" returns CaptureOperation.php because the embeddings are close, not because the file contains the word "capture".
Magento technology awareness — 20+ pattern detectors identify plugins, observers, controllers, blocks, cron jobs, GraphQL resolvers, DI preferences, layout XML, and more. Every search result is enriched with what kind of Magento component it is, so the AI client understands the code's role in the system.
Adaptive learning (SONA) — Magector tracks which results you actually use and adjusts future rankings with MicroLoRA feedback, getting smarter over time without any API calls.

The result: your AI assistant calls one MCP tool and gets ranked, pattern-enriched results in 10-45ms — instead of burning tokens grepping through dozens of wrong files. High relevance accuracy means the AI reads fewer, more targeted files, which optimizes context window usage, reduces API costs, and accelerates development cycles.

Approach	Semantic matches	Magento-aware	Speed (18K files)
`grep` / `ripgrep`	No	No	100-500ms
IDE search	No	No	200-1000ms
GitHub search	Partial	No	500-2000ms
Magector	Yes	Yes	10-45ms

Related MCP server: Axon.MCP.Server

Features

Semantic search -- find code by meaning, not exact keywords
99.2% accuracy -- validated with 101 E2E test queries across 16 tool categories, plus 557 Rust-level test cases
Hybrid search -- combines semantic vector similarity with keyword re-ranking for best-of-both-worlds results
Structured JSON output -- results include file path, class name, methods list, role badges, and content snippets for minimal round-trips
Persistent serve mode -- keeps ONNX model and HNSW index resident in memory, eliminating cold-start latency
Incremental re-indexing -- background file watcher detects changes and updates the index without restart (tombstone + compact strategy)
ONNX embeddings -- native 384-dim transformer embeddings via ONNX Runtime
36K+ vectors -- indexes the complete Magento 2 / Adobe Commerce codebase including framework internals
Magento-aware -- understands controllers, plugins, observers, blocks, resolvers, repositories, and 20+ Magento patterns
Adobe Commerce compatible -- works with both Magento Open Source and Adobe Commerce (B2B, Staging, and all Commerce-specific modules)
AST-powered -- tree-sitter parsing for PHP and JavaScript extracts classes, methods, namespaces, and inheritance
Cross-tool discovery -- tool descriptions include keywords and "See also" references so AI clients find the right tool on the first try
SONA feedback learning -- self-adjusting search that learns from MCP tool call patterns (e.g., search → find_plugin refines future rankings for similar queries)
SONA v2 with MicroLoRA + EWC++ -- rank-2 low-rank adapter (1536 params, ~6KB) adjusts query embeddings based on learned patterns; Elastic Weight Consolidation prevents catastrophic forgetting during online learning
Diff analysis -- risk scoring and change classification for git commits and staged changes
Complexity analysis -- cyclomatic complexity, function count, and hotspot detection across modules
Fast -- 10-45ms queries via persistent serve process, batched ONNX embedding with adaptive thread scaling
LLM description enrichment -- generate natural-language descriptions of di.xml files using Claude, stored in SQLite, and prepend them to embedding text so descriptions influence vector search ranking (not just post-retrieval display)
MCP server -- 47 tools integrating with Claude Code, Cursor, and any MCP-compatible AI tool
Clean architecture -- Rust core handles all indexing/search, Node.js MCP server delegates to it

Architecture

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

  F -->|"stdin/stdout JSON"| rust

  subgraph rust ["Rust Core"]
    direction TB
    A["AST Parser<br/>PHP · JS · XML"]
    B["Pattern Detection<br/>20+ Magento patterns"]
    B2["Description Enrichment<br/>LLM-powered di.xml summaries"]
    C["ONNX Embedder<br/>all-MiniLM-L6-v2 · 384d"]
    D["HNSW Vector Search<br/>hybrid reranking · 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[("HNSW Index")]
  A --> G["Metadata"] --> F

Search Pipeline

flowchart LR
  Q["Query"] --> E1["Synonym Enrichment"]
  E1 --> E2["ONNX Embedding"]
  E2 --> H["HNSW Search"]
  H --> R["Hybrid Reranking"]
  R --> SA["SONA Adjustment"]
  SA --> J["Structured JSON"]

Components

Component	Technology	Purpose
Embeddings	`ort` (ONNX Runtime)	all-MiniLM-L6-v2, 384 dimensions
Vector search	`hnsw_rs` + hybrid reranking	Approximate nearest neighbor + keyword boosting
PHP parsing	`tree-sitter-php`	Class, method, namespace extraction
JS parsing	`tree-sitter-javascript`	AMD/ES6 module detection
Pattern detection	Custom Rust	20+ Magento-specific patterns
CLI	`clap`	Command-line interface (index, search, serve, validate)
Unified metadata	rusqlite (bundled SQLite)	LLM descriptions, method-chain enrichment, process state, cache — all in .magector/data.db
SONA	Custom Rust	Feedback learning with MicroLoRA + EWC++
MCP server	`@modelcontextprotocol/sdk`	AI tool integration with structured JSON output
Config data	JSON exports in `.magector/config-data/`	One-time `core_config_data` exports per environment for config tracing

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 as of v2.15.1:

Path traversal protection

All tools that accept a path argument (magento_read, magento_grep, magento_ast_search, magento_find_dataobject_issues) route the input through safePath() / safeRelPath() helpers in src/mcp-server.js. These:

Resolve the argument against MAGENTO_ROOT with path.resolve() (normalizes .., symlinks are not followed during validation).
Reject any resolved path that does not lie inside MAGENTO_ROOT.

This prevents a hostile vendor/ comment from instructing the LLM to e.g. magento_read ../../home/user/.ssh/id_rsa. Both the standalone case handlers and their magento_batch counterparts share the same chokepoint.

Shell injection hardening in auto-update

src/update.js fetches the latest field from the npm registry and re-execs itself with the new version string. Previously this was interpolated into a shell command; a tampered registry response could inject shell metacharacters. As of v2.15.1:

The re-exec passes argv as an array to a no-shell spawner (no intermediate shell).
A semver-strict isSafeVersion() validator rejects any version string containing metacharacters or that does not match X.Y.Z / X.Y.Z-prerelease form.
Fails closed: the auto-update is silently skipped rather than run a malformed version.

Unix socket permissions

The serve-proxy Unix socket at .magector/serve.sock is created with chmod 0600 immediately after listen(). On multi-user systems, another local account can no longer connect and query the vector index (which would leak indexed source snippets). The chmod is best-effort on platforms that don't support it (logged to .magector/magector.log).

Reporting vulnerabilities

If you find a security issue, please open an issue on the GitHub repo and mark it as security-related. Do not post reproducers that leak actual source contents from private codebases.

Quick Start

Prerequisites

Node.js 18+

1. Initialize in Your Project

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

This single command handles the entire setup:

flowchart LR
  A["npx magector init"] --> B["Verify<br/>Project"]
  B --> C["Download<br/>ONNX Model"]
  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 --> 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

CLI Reference

Rust Core CLI

magector-core <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 ANTHROPIC_API_KEY)
  validate    Run validation suite (downloads Magento if needed)
  download    Download Magento 2 Open Source
  stats       Show index statistics
  embed       Generate embedding for text

`index`

magector-core index [OPTIONS]

Options:
  -m, --magento-root <PATH>          Path to Magento root directory
  -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)
  -v, --verbose                      Enable verbose output

When --descriptions-db is provided (or auto-detected as data.db next to the index), descriptions are prepended to the embedding text as "Description: {text}\n\n" before the raw file content. This places semantic terms within the 256-token ONNX window, significantly improving retrieval of di.xml files for natural-language queries.

`search`

magector-core search <QUERY> [OPTIONS]

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

`describe`

magector-core describe [OPTIONS]

Options:
  -m, --magento-root <PATH>   Path to Magento root directory
  -o, --output <PATH>         Output SQLite database [default: ./.magector/data.db]
      --force                 Re-describe all files (ignore cache)

Generates natural-language descriptions of di.xml files using the Anthropic API (Claude Sonnet). Requires ANTHROPIC_API_KEY environment variable. 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]

Starts a persistent process that reads JSON queries from stdin and writes JSON responses to stdout. Keeps the ONNX model and HNSW index resident in memory for fast repeated queries.

When --magento-root is provided, a background file watcher polls for changed files every --watch-interval seconds and incrementally re-indexes them without restart. Modified and deleted files are soft-deleted (tombstoned) in the HNSW index; new vectors are appended. When tombstoned entries exceed 20% of total vectors, the index is automatically compacted by rebuilding the HNSW graph.

Protocol (one JSON object per line):

// 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 + auto-reindex affected files):
{"command":"describe"}
// Response:
{"ok":true,"data":{"files_found":371,"described":5,"skipped":366,"errors":0,"described_paths":["app/code/..."]}}

// SONA feedback:
{"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}}

Node.js CLI

npx magector init [path]        # 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]    # Generate LLM descriptions for di.xml files
npx magector stats              # Show indexer statistics
npx magector setup [path]       # IDE setup only (no indexing)
npx magector mcp                # Start MCP server
npx magector help               # Show help

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 automatically. You can also set it manually 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	`./.magector/index.db`
`MAGECTOR_BIN`	Path to magector-core binary	Auto-detected
`MAGECTOR_MODELS`	Path to ONNX model directory	`~/.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.	Half of CPU 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 = faster, more RAM). Equivalent to `--batch-size`.	`256`
`ANTHROPIC_API_KEY`	API key for description generation (`describe` command)	—

Constraining CPU usage during indexing

Indexing a large enterprise codebase (~80K files) can saturate 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). 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 writes a crash-safe checkpoint to disk every 50 batches (~12,800 files). If the process is killed or times out mid-run, just re-run npx magector index — it auto-resumes from the last checkpoint:

npx magector index
# ♻️  Resuming from previous run: 38400 vectors across 12200 files already indexed
# ✓ Found 79771 total files; 12200 already indexed, 67571 remaining to process

The indexer collects already-embedded file paths from the existing DB, filters them out of file discovery, preserves the existing HNSW state, and only parses/embeds the files that aren't in the DB yet. Partial resume also picks up new files added to the tree since the previous run.

To force a full rebuild (e.g. after a schema change or if you want to discard stale vectors), pass --force:

npx magector index --force

MCP Server Tools

The MCP server exposes 47 tools for AI-assisted Magento 2 and Adobe Commerce development. All search tools return structured JSON with file paths, class names, methods, role badges, and content snippets -- enabling AI clients to parse results programmatically and minimize file-read round-trips.

Output Format

All search tools return structured JSON:

{
  "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 for quick assessment

Search Tools

Tool	Description
`magento_search`	Semantic search -- find any PHP class, method, XML config, template, or GraphQL schema by natural language
`magento_find_class`	Find PHP class, interface, abstract class, or trait by name
`magento_find_method`	Find method implementations across the codebase

Magento-Specific Finders

Tool	Description
`magento_find_config`	Find XML configuration (di.xml, events.xml, routes.xml, system.xml, webapi.xml, module.xml, layout)
`magento_find_template`	Find PHTML template files for frontend or admin rendering
`magento_find_plugin`	Find interceptor plugins (before/after/around methods) and di.xml declarations. Resolves plugin PHP files and extracts interceptor method signatures (v2.5)
`magento_find_fieldset`	Find fieldset.xml definitions controlling data copy between entities (order→quote, quote→order). Shows fields per aspect (to_order, to_edit) (v2.5)
`magento_find_observer`	Find event observers and events.xml declarations
`magento_find_preference`	Find DI preference overrides -- which class implements an interface
`magento_find_controller`	Find MVC controllers by frontend or admin route path
`magento_find_block`	Find Block classes for view rendering
`magento_find_graphql`	Find GraphQL schema definitions, resolvers, types, queries, and mutations
`magento_find_api`	Find REST/SOAP API endpoints in webapi.xml
`magento_find_cron`	Find cron job definitions in crontab.xml
`magento_find_db_schema`	Find database table definitions in db_schema.xml (declarative schema)

Flow & Dependency Tracing

Tool	Description
`magento_trace_flow`	Trace execution flow from an entry point (route, API, GraphQL, event, cron) -- maps controller → plugins → observers → templates with code snippets (v2.5)
`magento_trace_shipping_chain`	Trace the complete shipping rate chain: carriers → collectRates plugins → rate modifiers → totals collectors → fieldset mappings (v2.5)
`magento_trace_dependency`	Trace DI graph for a class/interface -- preferences, plugins, virtualTypes, argument overrides (parses all di.xml, no index needed)
`magento_find_event_flow`	Trace complete event chain: dispatchers → observers → handler PHP classes (parses events.xml + vector search)
`magento_find_event_dispatchers`	Find all PHP locations where a specific event is dispatched -- exact grep matching with method context and surrounding code (v2.3)
`magento_find_layout`	Find layout XML files by handle or content -- lists blocks, containers, and referenceBlock declarations
`magento_trace_data_flow`	Trace how a data attribute flows: find all setters (magic setter, setData, addData) and getters (magic getter, getData) across PHP and XML (v2.3)
`magento_trace_call_chain`	Trace internal method call chain: follows `$this->method()`, `$this->dep->method()`, and `dispatch()` calls to build an execution tree (v2.2)

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

Impact & Testing

Tool	Description
`magento_impact_analysis`	Analyze impact of changing a class -- finds use statements, DI references, direct instantiations, and type hints across the codebase
`magento_find_test`	Find PHPUnit tests for a given class/method -- searches Test/ directories for coverage, mocks, and assertions
`magento_find_implementors`	Find all classes implementing a given PHP interface -- scans `implements` keywords and di.xml `<preference>` declarations (v2.2)
`magento_find_callers`	Find all call sites of a method across PHP and XML files -- `->method()` and `::method()` calls (v2.2)
`magento_find_di_wiring`	Complete DI picture for a class: preferences, plugins, constructor args, virtual types, and argument overrides from di.xml (v2.2)

Diagnostics

Tool	Description
`magento_error_parser`	Parse Magento error messages and map to root cause, affected files, and fix suggestions (10 known patterns)
`magento_performance_profile`	Profile a Magento subsystem (checkout_totals, order_place, product_save, etc.) for performance bottlenecks -- plugins, observers, and complexity hotspots

Analysis Tools

Tool	Description
`magento_analyze_diff`	Analyze git diffs for risk scoring and change classification
`magento_complexity`	Analyze cyclomatic complexity, function count, and line count

Utility Tools

Tool	Description
`magento_module_structure`	Show complete module structure -- controllers, models, blocks, plugins, observers, configs
`magento_index`	Trigger re-indexing of the codebase (also kicks off background enrichment)
`magento_describe`	Generate LLM descriptions for di.xml files (requires `ANTHROPIC_API_KEY`), stored in `.magector/data.db`, auto-reindexes affected files
`magento_stats`	View index statistics
`magento_batch`	Execute multiple tool queries in parallel in one MCP roundtrip. Supports all search, find, grep, read, and null-risk tools. Use to avoid N×3-5s roundtrip overhead.
`magento_grep`	Exact text/regex search across PHP/XML/PHTML files (`grep -rn -E` internally). Supports `filesOnly` mode (like `grep -l`), `context` lines, `ignoreCase`, `include` patterns. (v2.9)
`magento_read`	Read a specific file with optional `methodName` extraction (~10× fewer tokens than reading the whole file) and `startLine`/`endLine` range. (v2.10)
`magento_trace_api`	Trace REST/GraphQL API endpoint from URL to implementation: webapi.xml → service interface → DI preference → method body. One call replaces 4-5 grep+read steps. (v2.11)
`magento_trace_config`	Trace a config path end-to-end: system.xml admin definition → PHP classes that consume the value → actual DB values from config-data exports. Accepts exact path or keyword search. (v2.17)
`magento_find_trigger`	Find database triggers across the codebase
`magento_find_table_usage`	Find all PHP code referencing a specific database table

Null-Safety Analysis (v2.12–v2.15)

Tool	Description
`magento_ast_search`	Structural PHP code search using tree-sitter. Named patterns: `dataobject-set-null` (detect setX(null) anti-pattern), `unchecked-method-chain` (detect $this->dep->method() chains). Pattern arg is an enum, not free-text. Executed in Rust serve process — no external dependency. (v2.16)
`magento_enrich`	Build the method-chain enrichment index. Scans all `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`. (v2.13, moved to Rust v2.16)
`magento_find_null_risks`	Query the enrichment index for method chains without null guards. O(1) SQLite query instead of file scanning. Pass `firstMethod` to filter (e.g., `"getPayment"` → all `->getPayment()->anything()` without null guard). Requires `magento_enrich`. (v2.13)
`magento_find_dataobject_issues`	Detect `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. Use during field-lifecycle audits or when debugging "value persists but shouldn't" bugs. Uses tree-sitter. (v2.15, tree-sitter v2.16)

Search Enhancements (v2.1)

Hybrid BM25+vector search -- combines text frequency scoring with semantic vector similarity for better exact class name matches
Query expansion -- automatically expands queries with Magento domain synonyms (plugin → interceptor, checkout → cart/quote/totals, etc.)
Module filtering -- moduleFilter parameter on magento_search to 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 reindex -- old index stays usable during background rebuild; new index is built to a temp path and swapped in atomically on completion

Deep Code Analysis (v2.2)

magento_find_implementors -- find all classes implementing a PHP interface (PHP implements + di.xml <preference>)
magento_find_callers -- find all call sites of a method across PHP and XML files
magento_find_di_wiring -- complete DI picture: preferences, plugins, constructor args, virtual types, argument overrides
magento_trace_call_chain -- trace internal method execution chain: $this->method(), $this->dep->method(), and dispatch() calls with event→observer resolution

Data Flow & Event Tracing (v2.3)

magento_trace_data_flow -- trace all setters and getters for a data attribute (magic methods, setData/getData, addData, constants, XML references). Answers "who writes/reads custom_discounted_price_incl_tax on Quote\Address?"
magento_find_event_dispatchers -- grep-based exact search for all PHP locations dispatching a specific event, with method context and surrounding code. Complements magento_find_event_flow with higher precision.
magento_find_plugin area context -- enriched output shows DI area (frontend/adminhtml/global/graphql) and explicit di.xml plugin registrations when targetClass is provided

Tool Cross-References

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

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 validated at two levels:

E2E MCP accuracy tests -- 101 queries across 16 tool categories via stdio JSON-RPC
Rust-level validation -- 557 test cases across 50+ categories against Magento 2.4.7

E2E Accuracy (MCP Tools)

---
config:
  themeVariables:
    pie1: "#4caf50"
    pie2: "#f44336"
---
pie title Test Pass Rate (101 queries)
  "Passed (101)" : 101
  "Failed (0)" : 0

Metric	Value
Grade	A+ (99.2/100)
Pass rate	101/101 (100%)
Precision	98.7%
MRR	99.3%
NDCG@10	98.7%
Index size	35,795 vectors
Query time	10-45ms

Integration Tests

66 integration tests covering MCP protocol compliance, tool schemas, tool calls (including magento_describe), analysis tools, and stdout JSON integrity.

Running Tests

# E2E accuracy tests (101 queries, requires indexed codebase)
npm run test:accuracy
npm run test:accuracy:verbose

# Integration tests (66 tests)
npm test

# SONA/MicroLoRA benefit evaluation (180 queries, baseline vs post-training)
npm run test:sona-eval
npm run test:sona-eval:verbose

# Rust validation (557 test cases)
cd rust-core && cargo run --release -- validate -m ./magento2 --skip-index

Project Structure

magector/
├── src/                          # Node.js source
│   ├── cli.js                    # CLI entry point (npx magector <command>)
│   ├── mcp-server.js             # MCP server (47 tools, structured JSON output)
│   ├── binary.js                 # Platform binary resolver
│   ├── model.js                  # ONNX model resolver/downloader
│   ├── init.js                   # Full init command (index + IDE config)
│   ├── magento-patterns.js       # Magento pattern detection (JS)
│   ├── templates/                # IDE rules templates
│   │   ├── cursorrules.js        # .cursorrules content
│   │   └── claude-md.js          # CLAUDE.md content
│   └── validation/               # JS validation suite
│       ├── validator.js
│       ├── benchmark.js
│       ├── test-queries.js
│       ├── test-data-generator.js
│       └── accuracy-calculator.js
├── tests/                        # Automated tests
│   ├── mcp-server.test.js        # Integration tests (64 tests)
│   ├── mcp-accuracy.test.js      # E2E accuracy tests (101 queries)
│   ├── mcp-sona.test.js          # SONA feedback integration tests (8 tests)
│   ├── mcp-sona-eval.test.js     # SONA/MicroLoRA benefit evaluation (180 queries)
│   ├── describe-benefit-eval.test.js  # Description enrichment benefit evaluation
│   └── results/                  # Test result artifacts
│       ├── accuracy-report.json
│       └── sona-eval-report.json
├── platforms/                    # Platform-specific binary packages
│   ├── darwin-arm64/             # macOS ARM (Apple Silicon)
│   ├── linux-x64/                # Linux x64
│   ├── linux-arm64/              # Linux ARM64
│   └── win32-x64/                # Windows x64
├── rust-core/                    # Rust high-performance core
│   ├── Cargo.toml
│   ├── src/
│   │   ├── main.rs               # Rust CLI (index, search, serve, validate)
│   │   ├── lib.rs                # Library exports
│   │   ├── indexer.rs             # Core indexing with progress output
│   │   ├── embedder.rs            # ONNX embedding (MiniLM-L6-v2)
│   │   ├── vectordb.rs            # HNSW vector database + hybrid search + tombstones
│   │   ├── watcher.rs             # File watcher for incremental re-indexing
│   │   ├── ast.rs                 # Tree-sitter AST (PHP + JS)
│   │   ├── magento.rs             # Magento pattern detection (Rust)
│   │   ├── describe.rs            # LLM description generation + SQLite storage
│   │   ├── sona.rs                # SONA feedback learning + MicroLoRA + EWC++
│   │   └── validation.rs          # 557 test cases, validation framework
│   └── models/                   # ONNX model files (auto-downloaded)
│       ├── all-MiniLM-L6-v2.onnx
│       └── tokenizer.json
├── .github/
│   └── workflows/
│       └── release.yml           # Cross-compile + publish CI
├── scripts/
│   └── setup.sh                  # Claude Code MCP setup script
├── config/
│   └── mcp-config.json           # MCP server configuration template
├── package.json
├── .gitignore
├── LICENSE
└── README.md

How It Works

1. Indexing

Magector scans every .php, .js, .xml, .phtml, and .graphqls file in a Magento 2 or Adobe Commerce codebase:

AST parsing -- Tree-sitter extracts class names, namespaces, methods, inheritance, and interface implementations from PHP and JavaScript files
Pattern detection -- Identifies Magento-specific patterns: controllers, models, repositories, plugins, observers, blocks, GraphQL resolvers, admin grids, cron jobs, and more
Search text enrichment -- Combines AST metadata with Magento pattern keywords to create semantically rich text representations
Description enrichment -- If a descriptions SQLite DB is present, LLM-generated natural-language descriptions are prepended to the embedding text as "Description: {text}\n\n", placing semantic DI concepts (preferences, plugins, virtual types, subsystem names) within the 256-token ONNX window
Embedding -- ONNX Runtime generates 384-dimensional vectors using all-MiniLM-L6-v2
Indexing -- Vectors are stored in an HNSW index for sub-millisecond approximate nearest neighbor search

2. Searching

Query text is enriched with pattern synonyms (e.g., "controller" adds "action execute http request dispatch")
The enriched query is embedded into the same 384-dimensional vector space
HNSW finds the nearest neighbors by cosine similarity
Hybrid reranking boosts results with keyword matches in path and search text
SONA adjustment -- MicroLoRA adapts the query embedding based on learned patterns; EWC++ prevents forgetting earlier learning
Results are returned as structured JSON with file path, class name, methods, role badges, and content snippet

3. Persistent Serve Mode

The MCP server spawns a persistent Rust process (magector-core serve) that keeps the ONNX model and HNSW index loaded in memory. Queries are sent as JSON over stdin and responses returned via stdout -- eliminating the ~2.6s cold-start overhead of loading the model per query. Falls back to single-shot execFileSync if the serve process is unavailable.

flowchart LR
  subgraph startup ["Startup (once)"]
    S1["Load Model"] --> S2["Load Index"] --> S3["Ready Signal"]
  end
  startup --> query
  subgraph query ["Per Query (10-45ms)"]
    Q1["stdin JSON"] --> Q2["Embed"] --> Q3["HNSW Search"] --> Q4["Rerank"] --> Q5["stdout JSON"]
  end
  subgraph fallback ["Fallback"]
    F1["execFileSync ~2.6s"]
  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 60 seconds (configurable via --watch-interval). Changed files are incrementally 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 tombstoned entries exceed 20% of total vectors, the HNSW graph is automatically rebuilt (compacted) to reclaim memory and restore search performance.

flowchart LR
  W1["Sleep 60s"] --> W2["Scan Filesystem"] --> W3{"Changes?"}
  W3 -->|No| W1
  W3 -->|Yes| W4["Tombstone Old Vectors"] --> W5["Parse + Embed New Files"] --> W6["Append to HNSW"] --> W7{"Tombstone > 20%?"}
  W7 -->|Yes| W8["Compact / Rebuild HNSW"] --> 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 all search/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 HNSW

  Dev->>AI: "checkout totals?"
  AI->>MCP: magento_search(...)
  MCP->>Rust: JSON query
  Rust->>HNSW: embed + search
  HNSW-->>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. Over time, this 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 immediately calls magento_find_plugin, SONA learns that similar queries should boost plugin results. The learned weights are persisted to a .sona file alongside 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`	Tracked for analysis

Characteristics:

Score adjustments are capped at ±0.15 to avoid overwhelming semantic similarity
Learning rate decays with repeated observations (diminishing returns)
Learned weights are keyed by normalized, order-independent query term hashes
Always active -- no feature flags or build-time opt-in required
Persisted via bincode to <db_path>.sona (e.g., .magector/index.db.sona)

SONA v2: MicroLoRA + EWC++

SONA v2 adds embedding-level adaptation via a MicroLoRA adapter and Elastic Weight Consolidation:

Component	Parameters	Purpose
MicroLoRA	1536 (rank-2, 2×384×2)	Adjusts query embeddings before HNSW search
EWC++	Fisher matrix (384 values)	Prevents catastrophic forgetting during online learning

adjust_query_embedding() applies the LoRA transform + L2 normalization before vector search; cosine similarity guard (≥0.90) skips destructive adjustments
learn_with_embeddings() updates LoRA weights from feedback signals with EWC regularization (λ=2000) and decaying learning rate
3-tier scoring with negative learning: positive signals boost the followed feature type, mild negative learning (0.1×) demotes unrelated types
V1→V2 persistence format is backward-compatible (auto-upgrades on load)

cd rust-core && cargo build --release

7. LLM Description Enrichment

Magector can generate natural-language descriptions of di.xml files using the Anthropic API and embed them directly into the vector index. This significantly improves search ranking for semantic queries about dependency injection.

Workflow:

# 1. Generate descriptions (one-time, 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 auto-reindexes affected files in one step.

How it works: Each di.xml file is sent to Claude Sonnet with a prompt optimized for semantic search retrieval. The resulting description (~70 words) is stored in a SQLite database (.magector/data.db). During indexing, descriptions are prepended to the embedding text as "Description: {text}\n\n" before the raw file content, placing semantic terms (preferences, plugins, virtual types, subsystem names) within the ONNX model's 256-token window.

Measured impact (A/B experiment, 25 queries, Magento 2.4.7, 17,891 vectors, 371 described files):

Metric	Without Descriptions	With Descriptions	Delta
Precision@K	1.6%	20.3%	+18.7%
MRR	0.031	0.330	+0.30
NDCG@10	0.037	0.369	+0.33
di.xml results/query	0.2	3.0	+2.8
Query win rate	—	—	76%

Magento Patterns Detected

mindmap
  root((Patterns))
    PHP
      Controller
      Model
      Repository
      Block
      Helper
      ViewModel
    Interception
      Plugin
      Observer
      Preference
    XML
      di.xml
      events.xml
      webapi.xml
      routes.xml
      crontab.xml
      db_schema.xml
    Frontend
      Template
      JavaScript
      GraphQL

Magector understands these Magento 2 architectural patterns:

Pattern	Detection Method	Example
Controller	Path + `execute()` method	`Controller/Adminhtml/Order/View.php`
Model	Path + extends `AbstractModel`	`Model/Product.php`
Repository	Path + implements `RepositoryInterface`	`Model/ProductRepository.php`
Block	Path + extends `AbstractBlock`	`Block/Product/View.php`
Plugin	Path + before/after/around methods	`Plugin/Product/SavePlugin.php`
Observer	Path + implements `ObserverInterface`	`Observer/ProductSaveObserver.php`
GraphQL Resolver	Path + implements `ResolverInterface`	`Model/Resolver/Products.php`
Helper	Path under `Helper/`	`Helper/Data.php`
Cron	Path under `Cron/`	`Cron/CleanExpiredQuotes.php`
Console Command	Path + extends `Command`	`Console/Command/IndexerReindex.php`
Data Provider	Path + `DataProvider`	`Ui/DataProvider/Product/Listing.php`
ViewModel	Path + implements `ArgumentInterface`	`ViewModel/Product/Breadcrumbs.php`
Setup Patch	Path + `Patch/Data` or `Patch/Schema`	`Setup/Patch/Data/AddAttribute.php`
di.xml	Path matching	`etc/di.xml`, `etc/frontend/di.xml`
events.xml	Path matching	`etc/events.xml`
webapi.xml	Path matching	`etc/webapi.xml`
layout XML	Path 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`

Configuration

Cursor IDE Rules

Copy .cursorrules to your Magento project root for optimized AI-assisted development. The rules instruct the AI to:

Use Magector MCP tools before reading files manually
Write effective semantic queries
Follow Magento development patterns
Interpret search results correctly

Excluding Directories (`.magectorignore`)

Magector automatically skips common non-project directories during indexing:

vendor/ — Composer dependencies (100K-500K files)
node_modules/ — npm packages
generated/ — DI-compiled files
var/ — cache, logs, sessions
pub/static/ — deployed static assets
dev/tests/, dev/tools/ — Magento development tools
Test/, Tests/, test/, tests/ — test directories
.git/ — version control

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

# .magectorignore — additional directories to exclude from Magector indexing
# One pattern per line, gitignore-like syntax

# 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

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/:

# MySQL 8.0+ with --json flag
mysql -u user -p magento_db -e "SELECT scope, scope_id, path, value FROM core_config_data" --json > .magector/config-data/CZ-production.json

# Older MySQL (no --json): pipe through python3
mysql -u user -p magento_db -B -e "SELECT scope, scope_id, path, value FROM core_config_data" | \
  python3 -c "import sys,json; lines=sys.stdin.read().strip().split('\n'); h=lines[0].split('\t'); \
  rows=[dict(zip(h,l.split('\t'))) for l in lines[1:]]; [r.update({'scope_id':int(r['scope_id'])}) for r in rows]; \
  json.dump(rows,sys.stdout,indent=2)" > .magector/config-data/CZ-production.json

# Or from n8n/API/any tool that produces:
# [{scope, scope_id, path, value}, ...]

File naming: Use {country}-{environment}.json, e.g.:

CZ-production.json
SK-staging.json
IT-production.json

When magento_trace_config traces a config path, it automatically looks up values from all available exports and shows them per environment.

Model Configuration

The ONNX model (all-MiniLM-L6-v2) is automatically downloaded on first run to ~/.magector/models/. To use a different location:

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

Development

Building from Source

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 will automatically find 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

# Run validation
cargo run --release -- validate

Testing

# Integration tests (66 tests, requires indexed codebase)
npm test

# E2E accuracy tests (101 queries)
npm run test:accuracy
npm run test:accuracy:verbose

# Run without index (unit + schema tests only)
npm run test:no-index

# Rust unit tests (37 tests including SONA + descriptions)
cd rust-core && cargo test

# SONA integration tests (8 tests)
node tests/mcp-sona.test.js

# SONA/MicroLoRA benefit evaluation (180 queries)
npm run test:sona-eval

# Rust validation (557 test cases)
cd rust-core && cargo run --release -- validate -m ./magento2 --skip-index

Adding New Magento Patterns

Add pattern detection in rust-core/src/magento.rs
Add search text enrichment in rust-core/src/indexer.rs
Add validation test cases in rust-core/src/validation.rs
Add E2E accuracy test cases in tests/mcp-accuracy.test.js
Rebuild and run validation to verify:

cargo build --release
./target/release/magector-core validate -m ./magento2 --skip-index
npm run test:accuracy

Adding MCP Tools

Define the tool schema in src/mcp-server.js (ListToolsRequestSchema handler)
Include keyword-rich descriptions and cross-tool "See also" references
Implement the handler in the CallToolRequestSchema handler
Return structured JSON via formatSearchResults()
Add E2E test cases in tests/mcp-accuracy.test.js
Test with Claude Code or the MCP inspector

Technical Details

Embedding Model

Model: all-MiniLM-L6-v2
Dimensions: 384
Pooling: Mean pooling with attention mask
Normalization: L2 normalized
Runtime: ONNX Runtime (via ort crate)

Vector Index

Algorithm: HNSW (Hierarchical Navigable Small World)
Library: hnsw_rs
Parameters: M=32, max_layers=16, ef_construction=200
Distance metric: Cosine similarity
Hybrid search: Semantic nearest-neighbor + keyword reranking in path and search text + SONA/MicroLoRA feedback adjustments
Incremental updates: Tombstone soft-delete + periodic HNSW rebuild (compact)
Persistence: Bincode V2 binary serialization (backward-compatible with V1)

Index Structure

Each indexed file produces a vector entry with metadata:

struct IndexMetadata {
    path: String,
    file_type: String,          // php, xml, js, template, graphql
    magento_type: String,       // controller, model, block, plugin, ...
    class_name: Option<String>,
    namespace: Option<String>,
    methods: Vec<String>,       // extracted method names
    search_text: String,        // enriched searchable text
    is_controller: bool,
    is_plugin: bool,
    is_observer: bool,
    is_model: bool,
    is_block: bool,
    is_repository: bool,
    is_resolver: bool,
    // ... 20+ pattern flags
}

Performance Characteristics

Operation	Time	Notes
Full index (36K vectors)	~1 min	Parallel parsing + batched ONNX embedding
Single query (warm)	10-45ms	Persistent serve process, HNSW + rerank
Single query (cold)	~2.6s	Includes ONNX model + index load
Embedding generation	~2ms	ONNX Runtime with CoreML/CUDA
Batch embedding (32)	~30ms	Batched ONNX inference
Model load	~500ms	One-time at startup
Index save/load	<1s	Bincode binary serialization

Performance Optimizations

Persistent serve mode -- Rust process keeps ONNX model + HNSW index in memory via stdin/stdout JSON protocol
Query cache -- LRU cache (200 entries) avoids re-embedding identical queries
Hybrid reranking -- combines semantic similarity with keyword matching for better precision
Batched ONNX embedding -- 32 texts per inference call (vs. 1-at-a-time), 3-5x faster embedding
Dynamic thread scaling -- ONNX intra-op threads scale to CPU core count
Thread-local AST parsers -- each rayon thread gets its own tree-sitter parser (no mutex contention)
Bincode persistence -- binary serialization replaces JSON (3-5x faster save/load, ~5x smaller files)
Adaptive HNSW capacity -- pre-sized to actual vector count
Parallel HNSW insert -- batch insert uses hnsw_rs parallel insertion on load and index
Tuned ef_search -- optimized search parameters for 36K vector index (ef_search=50 for search, 64 for hybrid)
SONA feedback learning -- learns from MCP tool call patterns to adjust search rankings; MicroLoRA adapts query embeddings, EWC++ prevents forgetting

Roadmap

gantt
  title Roadmap
  dateFormat YYYY-MM
  axisFormat %b
  section Done
    Hybrid search       :done, 2025-01, 30d
    Serve mode          :done, 2025-02, 30d
    JSON output         :done, 2025-03, 15d
    Cross-tool hints    :done, 2025-03, 15d
    E2E tests           :done, 2025-03, 15d
    Adobe Commerce      :done, 2025-03, 15d
  section Next
    SONA feedback       :done, 2025-04, 30d
    Incremental index   :done, 2025-04, 30d
    SONA v2 MicroLoRA   :done, 2025-05, 15d
    LLM descriptions    :done, 2025-06, 30d
    Method chunking     :active, 2025-07, 30d
    Intent detection    :2025-08, 30d
    Type filtering      :2025-09, 30d
  section Future
    VSCode extension    :2025-10, 60d
    Web UI              :2025-12, 60d

Hybrid search (semantic + keyword re-ranking)
Persistent serve mode (eliminates cold-start latency)
Structured JSON output (methods, badges, snippets)
Cross-tool discovery hints for AI clients
E2E accuracy test suite (101 queries)
Adobe Commerce support (B2B, Staging, and all Commerce-specific modules)
SONA feedback learning (search rankings adapt to MCP tool call patterns)
SONA v2 with MicroLoRA + EWC++ (embedding-level adaptation, prevents catastrophic forgetting)
LLM description enrichment (generate di.xml descriptions via Claude, store in SQLite, embed into vectors for improved search ranking)
Method-level chunking (per-method vectors for direct method search)
Query intent classification (auto-detect "give me XML" vs "give me PHP")
Filtered search by file type at the vector level
Incremental indexing (background file watcher with tombstone + compact strategy)
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, enrichment progress
`WARN`	Recoverable issues: slow grep queries (>5s), missing data.db, file read errors, serve process disconnects
`ERR`	Failures: AST query errors, transaction rollbacks, 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

# Enrichment/null-risk analysis
grep 'enrich:\|null_risks:' .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/magento.log | tail -20

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

What Gets Logged (v2.14+)

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_enrich — file count, progress every 10k files, read errors, transaction failures, final summary
magento_find_null_risks — query parameters, result count, query timing, missing DB warnings
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

License

MIT License. See LICENSE for details.

Contributing

Contributions are welcome. Please:

Fork the repository
Create a feature branch (git checkout -b feature/improvement)
Add tests for new functionality
Run validation to ensure accuracy doesn't regress: npm run test:accuracy
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.

ParametersJSON Schema

Name	Required	Description	Default
`staged`	No	Set true to analyze staged changes, false to require commitHash. Default: true.
`commitHash`	No	Git 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_ast_searchA

Structural PHP code search using tree-sitter AST queries. Unlike magento_grep (text-based), this understands PHP AST — matches code structure regardless of variable names, ignores comments/strings. Available named patterns: "dataobject-set-null" (finds ->setX(null) anti-pattern calls), "unchecked-method-chain" (finds ->a()->b() chains without null guards). Uses Rust tree-sitter for fast, accurate parsing. ⚡ For multi-query workflows use magento_batch.

ParametersJSON Schema

Name	Required	Description
`path`	No	Subdirectory to search (relative to MAGENTO_ROOT). Default: entire codebase. Example: "vendor/acme/"
`pattern`	Yes	Named AST query pattern. "dataobject-set-null": finds ->setX(null) calls on DataObjects. "unchecked-method-chain": finds ->a()->b() chains without null guards.
`maxResults`	No	Maximum matches to return (default: 50, max: 200)

TDQS

A4.8/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 uses Rust tree-sitter for fast, accurate parsing and that it ignores comments/strings. This is good, but it doesn't explicitly state whether the tool is read-only or if it modifies state (likely read-only). A score of 4 reflects strong transparency with a minor gap in safety disclosure.

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 and well-structured. It begins with a clear statement of functionality, then distinguishes from a sibling, lists available patterns with examples, and ends with a performance note and a usage tip. 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 medium complexity and the absence of an output schema, the description is complete. It covers purpose, usage guidelines, behavioral traits (speed, AST awareness), and parameter details. No additional context is needed for effective agent use.

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%, so baseline is 3. The description adds significant value by explaining each named pattern in detail, describing the default for 'path' and the default/max for 'maxResults'. This goes beyond the schema's minimal descriptions, making parameter semantics very clear.

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 performs structural PHP code search using tree-sitter AST queries. It distinguishes itself from the sibling 'magento_grep' by explicitly noting that it understands PHP AST, matches code structure regardless of variable names, and ignores comments and strings, which provides a specific and differentiated 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?

The description provides explicit guidance on when to use this tool: for AST-based structural search, contrasted with text-based 'magento_grep'. It also mentions available named patterns with examples, and advises using 'magento_batch' for multi-query workflows, giving clear context on when not to use it.

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.

ParametersJSON Schema

Name	Required	Description	Default
`queries`	Yes	Array 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.

ParametersJSON Schema

Name	Required	Description
`path`	No	Specific file or directory path to analyze instead of a module name
`module`	No	Magento module to analyze. Finds all PHP files in the module. Examples: "Magento_Catalog", "Magento_Checkout", "Magento_Sales"
`threshold`	No	Minimum 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.

ParametersJSON Schema

Name	Required	Description	Default
`force`	No	Force 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.

ParametersJSON Schema

Name	Required	Description	Default
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.

ParametersJSON Schema

Name	Required	Description	Default
`error`	Yes	Full 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).

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	API endpoint URL pattern or service method name. Examples: "/V1/products", "/V1/orders", "/V1/carts", "/V1/customers", "/V1/categories", "getList", "save"
`method`	No	Filter 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.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	Block 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.

ParametersJSON Schema

Name	Required	Description	Default
`className`	No	Optional: class that owns the method — narrows results to files that reference this class. Examples: "SalesRuleManagement", "CartRepository"
`methodName`	Yes	Method 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).

ParametersJSON Schema

Name	Required	Description	Default
`className`	Yes	Full or partial PHP class name. Examples: "ProductRepository", "AbstractModel", "CartManagementInterface", "CustomerData", "StockItemRepository"
`namespace`	No	Optional 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).

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	What configuration to find. Examples: "di.xml preference for ProductRepository", "routes.xml catalog", "system.xml payment field", "events.xml checkout", "layout xml catalog_product_view"
`configType`	No	Type 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.

ParametersJSON Schema

Name	Required	Description	Default
`area`	No	Magento area: frontend (storefront routes) or adminhtml (admin panel routes)
`route`	Yes	URL 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.

ParametersJSON Schema

Name	Required	Description	Default
`jobName`	Yes	Cron 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.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No	Subdirectory to search (relative to MAGENTO_ROOT). Default: entire codebase. Example: "vendor/acme/"
`maxResults`	No	Maximum 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).

ParametersJSON Schema

Name	Required	Description	Default
`tableName`	Yes	Database 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.

ParametersJSON Schema

Name	Required	Description	Default
`className`	Yes	Full 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?".

ParametersJSON Schema

Name	Required	Description	Default
`eventName`	Yes	Magento 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.

ParametersJSON Schema

Name	Required	Description	Default
`eventName`	Yes	Magento 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.

ParametersJSON Schema

Name	Required	Description	Default
`aspect`	No	Aspect name filter. Examples: "to_order", "to_edit", "to_quote", "to_customer"
`fieldset`	No	Fieldset 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).

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	GraphQL type, query, mutation, or interface name. Examples: "products", "createCustomer", "CartItemInterface", "cart", "categoryList", "placeOrder", "createEmptyCart"
`schemaType`	No	Filter 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.

ParametersJSON Schema

Name	Required	Description	Default
`interfaceName`	Yes	Full 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.

ParametersJSON Schema

Name	Required	Description	Default
`query`	No	Search term to find in layout XML content. Examples: "product.info", "checkout.cart", "minicart", "breadcrumbs", "page.main.title"
`handle`	No	Layout 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).

ParametersJSON Schema

Name	Required	Description	Default
`className`	No	Optional class name to narrow method search. Example: "ProductRepository"
`methodName`	Yes	PHP 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.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum results (default: 100, max: 500)
`firstMethod`	No	Filter 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.

ParametersJSON Schema

Name	Required	Description	Default
`eventName`	Yes	Magento 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.

ParametersJSON Schema

Name	Required	Description	Default
`targetClass`	No	Class being intercepted by plugins. Examples: "ProductRepository", "CartManagement", "CustomerRepository", "OrderRepository", "Topmenu"
`targetMethod`	No	Specific 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.

ParametersJSON Schema

Name	Required	Description	Default
`interfaceName`	Yes	Interface 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.

ParametersJSON Schema

Name	Required	Description	Default
`tableName`	Yes	Database 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).

ParametersJSON Schema

Name	Required	Description	Default
`area`	No	Magento area: frontend (customer-facing storefront), adminhtml (admin panel), base (shared/fallback)
`query`	Yes	Template 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.

ParametersJSON Schema

Name	Required	Description	Default
`className`	Yes	PHP class name to find tests for. Examples: "ProductRepository", "CartManagement", "OrderService"
`methodName`	No	Optional 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.

ParametersJSON Schema

Name	Required	Description	Default
`tableName`	No	Optional table name to find triggers targeting this table.
`triggerName`	No	Optional 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.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No	Subdirectory to search in (relative to MAGENTO_ROOT). Default: "." (entire codebase). Examples: "vendor/acme/", "app/code/", "vendor/magento/module-sales/"
`context`	No	Lines of context around each match (default: 4). Like grep -C. Use 0 for broad scans with many matches, then batch-read specific files.
`include`	No	File glob pattern to include. Default: ".php". Examples: ".xml", ".{php,xml}", ".js", "*.phtml"	*.php
`pattern`	Yes	Text pattern to search for. Literal string or POSIX regex. Examples: "getPayment()->getMethod()", "removeButton", "sales_order_place_after", "class AddressConditions"
`filesOnly`	No	Return 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.
`ignoreCase`	No	Case-insensitive search (default: false)
`maxResults`	No	Maximum 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.

ParametersJSON Schema

Name	Required	Description	Default
`className`	Yes	Full 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.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No	Absolute 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.

ParametersJSON Schema

Name	Required	Description	Default
`moduleName`	Yes	Full 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.

ParametersJSON Schema

Name	Required	Description	Default
`subsystem`	Yes	Magento subsystem to profile. Examples: "checkout_totals", "order_place", "product_save", "cart_add", "customer_login", "catalog_reindex"
`threshold`	No	Minimum 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.

ParametersJSON Schema

Name	Required	Description
`path`	Yes	File path relative to MAGENTO_ROOT. Example: "vendor/acme/module-sales/Model/OrderService.php"
`endLine`	No	Stop reading at this line number (inclusive). Default: end of file. Use with startLine for large files.
`startLine`	No	Start reading from this line number (1-based). Default: 1 (beginning of file).
`methodName`	No	Extract 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_searchA

Search Magento codebase semantically — find any PHP class, method, XML config, PHTML template, JS file, or GraphQL schema by describing what you need in natural language. Use this as a general-purpose search when no specialized tool fits. Works best for Magento core and popular vendor modules. For small/custom project-specific modules (e.g. proprietary modules not widely known to the embedding model), use magento_grep instead — semantic search may return 0 results for these. See also: magento_find_class, magento_find_method, magento_find_config for targeted searches.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum results to return (default: 10, max: 100)
`query`	Yes	Natural language search query describing what you want to find. Examples: "product price calculation logic", "checkout controller", "customer authentication", "add to cart", "order placement flow"
`expand`	No	Enable query expansion with Magento domain synonyms for better recall (default: true)
`precise`	No	Precise mode for debugging: disables query expansion AND applies strict post-filtering — only returns results where the file content contains at least one query keyword. Use for specific debugging queries like "gift card subtotal infinite loop". Default: false.
`moduleFilter`	No	Filter results by vendor/module pattern(s). Accepts a single string or array of strings. Supports wildcards and vendor prefix matching. Uses "/" or "_" interchangeably as separator. Examples: "Vendor_*", ["Acme_PaymentGateway", "Acme_FreeShipping"], "Magento_Catalog".
`excludeModuleFilter`	No	Exclude results from vendor/module pattern(s). Inverse of moduleFilter — removes matching modules from results. Same pattern syntax as moduleFilter. Useful when you know which modules are irrelevant. Examples: "Vendor_MarketplaceBase", ["Vendor_ModuleA", "Vendor_ModuleB"].

TDQS

A4.6/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 limitations: 'Works best for Magento core... semantic search may return 0 results' for custom modules. It also explains behavioral effects of parameters like 'precise' and 'expand'. However, it does not explicitly state that the tool is read-only or mention any side effects. Still, the provided limitations and parameter behavior give solid 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?

Description is front-loaded with the main purpose and usage context. Every sentence serves a purpose: first defines tool, second gives usage guidelines, third mentions limitations, fourth lists alternatives. No redundant or filler text. It is appropriately sized for the tool's complexity.

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 large set of sibling tools, the description adequately positions this tool as a general-purpose fallback and explains its limitations regarding custom modules. However, it does not describe the return format or ranking behavior, which could help an agent interpret results. Since no output schema is provided, a brief note on what results look like would improve completeness.

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%, so baseline is 3. The description adds meaningful context beyond the schema: for 'precise' it clarifies 'disables query expansion AND applies strict post-filtering'; for 'expand' it mentions 'Magento domain synonyms'; and for query it provides concrete examples. This adds value for an agent to construct proper requests.

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 a clear verb+resource: 'Search Magento codebase semantically... find any PHP class, method, XML config...' It specifies the resource (Magento codebase) and the action (semantic search). Additionally, it distinguishes itself from sibling tools by stating 'Use this as a general-purpose search when no specialized tool fits' and listing alternatives like 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 when to use: 'general-purpose search when no specialized tool fits' and when not to use: 'for small/custom project-specific modules... use magento_grep instead.' It also references sibling tools with 'See also: magento_find_class, magento_find_method, magento_find_config for targeted searches.' This provides clear guidance on tool selection.

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.

ParametersJSON Schema

Name	Required	Description	Default
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.

ParametersJSON Schema

Name	Required	Description
`url`	No	REST API URL pattern to trace. Example: "/V1/orders/:orderId/items", "/V1/carts/mine/payment-information"
`method`	No	HTTP method (GET, PUT, POST, DELETE). Default: any.
`interfaceName`	No	Alternative: 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.

ParametersJSON Schema

Name	Required	Description
`maxDepth`	No	Maximum recursion depth for tracing (default: 3). Higher values trace deeper but take longer.
`className`	Yes	Full PHP class name (FQCN) to start tracing from. Examples: "Vendor\OrderSplit\Model\CreateOrder\CreateChildOrder", "Magento\Quote\Model\QuoteManagement"
`methodName`	Yes	Method 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.

ParametersJSON Schema

Name	Required	Description	Default
`keyword`	No	Keyword to search for in system.xml fields when exact path is unknown. Example: "marketplace_payment", "cashondelivery". Returns all matching config paths.
`configPath`	No	Exact 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.

ParametersJSON Schema

Name	Required	Description	Default
`modelClass`	No	Optional: model class name to prioritize results that reference this class. Examples: "Quote\Address", "Order", "Product"
`attributeKey`	Yes	The 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.

ParametersJSON Schema

Name	Required	Description	Default
`className`	Yes	Full or partial PHP class/interface name to trace. Examples: "ProductRepositoryInterface", "CartManagementInterface", "LoggerInterface", "StoreManagerInterface"
`direction`	No	"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.

ParametersJSON Schema

Name	Required	Description	Default
`depth`	No	Trace depth. "shallow" traces entry point + config + direct plugins (faster). "deep" adds observers, layout, templates, and DI preferences (more complete). Default: shallow.	shallow
`entryType`	No	Type of entry point. "auto" detects from the pattern (default). Override when auto-detection is wrong.	auto
`entryPoint`	Yes	The 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.

ParametersJSON Schema

Name	Required	Description	Default
`carrier`	No	Optional 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.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0

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

ActivityMaintained

ResponsivenessSyncing

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

gread A
io.github.NitroRCr
An MCP server that gives your AI access to the source code and docs of all public github repos
Version Control Code Analysis Documentation Access
5361
Artificial Wit AI
com.artificialwit
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
ERP Systems CRM Knowledge & Memory
2
mcp A
ai.llmse
Public MCP server for the LLM Search Engine
Search RAG Systems Developer Tools
102
H-Index A
ai.xr-utilities
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
Search Documentation Access
32

Related MCP Servers

SRC (Structured Repo Context)
Developer Tools RAG Systems Search
kvnpetit
A
license
A
quality
C
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.
Updated 6 months ago (2026-02-27 21:14 UTC)
5
28
1
MIT
Axon.MCP.Server
Code Analysis Developer Tools Search
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.
Updated 2 months ago (2026-06-30 01:32 UTC)
166
code-context-mcp
Code Analysis Search Knowledge & Memory
RafaelC457ro
A
license
Not graded
quality
C
maintenance
MCP server for semantic code search and dependency graph analysis. Indexes codebases into a knowledge graph with vector embeddings for AI-powered code understanding.
Updated a month ago (2026-07-30 16:15 UTC)
32
MIT
codebaxing
Code Analysis RAG Systems
duysolo
A
license
A
quality
F
maintenance
MCP server for semantic code search that indexes your codebase and allows AI editors to search using natural language queries.
Updated 5 months ago (2026-03-31 14:53 UTC)
9
112
53
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/krejcif/magector'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

Magector

Why Magector

Features

Architecture

Indexing Pipeline

Search Pipeline

Components

Security

Path traversal protection

Shell injection hardening in auto-update

Unix socket permissions

Reporting vulnerabilities

Quick Start

Prerequisites

1. Initialize in Your Project

2. Search

3. Re-index After Changes

4. IDE Setup Only (Skip Indexing)

CLI Reference

Rust Core CLI

index

search

describe

serve

Node.js CLI

Environment Variables

Constraining CPU usage during indexing

Resume after timeout or interrupt

MCP Server Tools

Output Format

Search Tools

Magento-Specific Finders

Flow & Dependency Tracing

Impact & Testing

Diagnostics

Analysis Tools

Utility Tools

Null-Safety Analysis (v2.12–v2.15)

Search Enhancements (v2.1)

Deep Code Analysis (v2.2)

Data Flow & Event Tracing (v2.3)

Tool Cross-References

Query Examples

Supported Platforms

Validation

E2E Accuracy (MCP Tools)

Integration Tests

Running Tests

Project Structure

How It Works

1. Indexing

2. Searching

3. Persistent Serve Mode

4. File Watcher (Incremental Re-indexing)

5. MCP Integration

6. SONA Feedback Learning

7. LLM Description Enrichment

Magento Patterns Detected

Configuration

Cursor IDE Rules

Excluding Directories (.magectorignore)

Config Data (core_config_data exports)

Model Configuration

Development

Building from Source

Building

Testing

Adding New Magento Patterns

Adding MCP Tools

Technical Details

Embedding Model

Vector Index

Index Structure

Performance Characteristics

Performance Optimizations

Roadmap

Troubleshooting

Log Levels

Common Diagnostic Commands

What Gets Logged (v2.14+)

`index`

`search`

`describe`

`serve`

Excluding Directories (`.magectorignore`)