magento-sql-mcp-server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v2.4.0
Disambiguation5/5
Every tool has a clearly defined, distinct purpose with explicit 'does NOT' notes to prevent overlap. For instance, get_indexer_status vs get_cron_schedule, get_active_quote_items vs find_active_quote_by_email, and get_largest_tables vs get_heavy_log_tables all address separate concerns. The descriptions effectively eliminate ambiguity.
Naming Consistency5/5
Tool names follow a highly consistent verb_noun pattern: get_ for retrieval, find_ for lookups, list_ for enumerations, describe_/search_/count_/explain_ for specific operations, and a few bespoke verbs like audit_/detect_/run_. The naming is uniform and predictable across all 44 tools, making it easy to anticipate tool behavior.
Tool Count2/5
With 44 tools, the surface is substantially overloaded. While Magento is a complex system, the sheer number forces agents to wade through many highly specific tools, increasing selection error risk. Typical well-scoped servers hold 3–15 tools; this exceeds the '25+' threshold for excessive count and feels heavy even for a comprehensive Magento diagnostics suite.
Completeness4/5
The server covers a broad range of Magento database operations: order/product/customer lookups, EAV, categories, CMS, cron, staging, B2B, MSI, queue monitoring, secrets audit, and health checks. The generic execute_select_query handles ad-hoc queries, filling most gaps. Minor missing areas like sales reports or customer group queries are not directly tooled but are reachable via raw SQL, so no dead ends exist.
Average 4.3/5 across 44 of 44 tools scored. Lowest: 3.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which covers the safety profile. The description adds genuinely useful behavior beyond annotations: the auto-appended LIMIT 100 (prevents unbounded result sets) and the masking of sensitive columns (password, token, cc_). No contradiction between description and annotations.
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?
Three sentences with no filler. Core purpose is front-loaded, followed by the safety-relevant auto-limit, parameter note, and masking disclosure. Each sentence earns its place. Slightly more verbose than strictly necessary, but efficient for a tool with this much behavioral nuance.
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 raw SQL executor, the description is largely complete: allowed query types, auto-limit, masking behavior, and an output schema are all present. Combined with annotations covering the safety profile and idempotency, an agent has what it needs to invoke the tool and interpret results. Missing only explicit guidance on which sibling to reach for instead, which is covered under usage_guidelines.
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 input schema fully documents all five parameters, including the limit default (100) and hard cap (1000), the query alias, and the profile and magentoRoot overrides. The description adds only marginal value by restating the sql/query alias relationship and referencing the auto-limit. At full coverage, the 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 states a specific verb ('Runs') with an explicit resource ('the Magento database') and enumerates the allowed query types (SELECT/SHOW/DESCRIBE/EXPLAIN). This clearly differentiates it from the many specialized sibling tools (find_order_by_increment_id, get_indexer_status, etc.) as the raw SQL executor. No ambiguity about what this tool does.
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 gives no guidance on when to prefer this tool over its 46+ siblings, such as validate_select_query or explain_select_query. There is no when/when-not language or alternative routing. It's implied that this is for ad-hoc queries not covered by specialized finders, but that is left entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nuance about approximate vs. exact counts and the safety advantage over SELECT *, which goes beyond the annotations. Yet it doesn't clarify when approximate vs. exact occurs or address rate limits or auth, which are not covered by annotations. The addition is modest.
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 three sentences with zero fluff. The primary function comes first, followed by a safety note and a concrete usage tip. Every sentence earns its place, and the structure guides the agent from what → why → when.
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 single-required-parameter tool with an output schema present, the description covers the essential aspects: what it does, safety characteristics, and a common use case. It doesn't elaborate on return format or edge cases, but the output schema handles return details, and the description's core guidance is sufficient. A minor gap is the lack of explicit mention that the count is not guaranteed exact for InnoDB tables, but that's implied by 'approximate or exact.'
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% — all three parameters (table, profile, magentoRoot) include descriptive text in the schema. The description itself adds no parameter-level detail beyond the schema. Per the baseline, when coverage is high, a 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's core function: 'Returns approximate or exact row count for a single table.' The verb 'returns' and the resource 'row count for a single table' are specific, and the safety note ('Safer than SELECT *') distinguishes it from data-retrieval tools like execute_select_query. It also implies a singular table scope, differentiating it from tools like get_largest_tables.
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 'Use before execute_select_query to gauge table size,' providing a clear when-to-use directive. It also conveys safety relative to SELECT * on large tables, which implies it's intended for size estimation rather than data retrieval. However, it doesn't explicitly mention alternatives like explain_select_query or get_largest_tables, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context that the data is persisted and not recalculated, which goes beyond annotations and clarifies the nature of the read.
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 plus a brief note, with the primary action stated first and the clarifying constraint (no recalculation) immediately after. Every word earns its place; no filler or repetition.
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 rich annotations, a 100%-described schema, and an output schema handling return values, the description covers the essential behavior. It could mention preconditions like connection profile requirements, but those are handled by other tools and the schema. Minor gap only.
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 schema description coverage is 100% for all three parameters, so the schema already documents them thoroughly. The description only repeats that the lookup is by increment_id, adding no new meaning beyond what the schema 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 states a specific verb (Returns), a clear resource (tax rates and amounts on an order), and the identifier (increment_id). It also clarifies what it does NOT do (recalculate tax), which distinguishes it from calculation tools and it clearly differs from sibling find_order_by_increment_id.
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 clarifies scope by stating it reads persisted sales_order_tax rows and does not recalculate, but it never explicitly names an alternative or says when to prefer this over other order-related tools. Usage timing is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering safety behavior. The description adds the return fields and the pattern-matching semantics, which is useful but not extensive. It does not contradict the annotations and provides some extra context (e.g., that it searches by pattern).
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 unnecessary words. The first sentence states the verb, resource, and matching behavior; the second lists return fields and use cases. Information is front-loaded and every clause 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?
Given the presence of an output schema, the description need not explain return structures. It covers the purpose, return fields, and typical scenarios. For a read-only search tool with strong annotations and full schema coverage, nothing critical is missing. It could have mentioned pattern breadth or pagination, but those are minor and likely covered by the output schema.
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 all parameters fully documented (path_pattern includes example and SQL LIKE semantics, profile and magentoRoot have clear explanations). The tool description adds the concept of matching both request_path and target_path, but this is already explicit in the schema. Thus the description adds little beyond the structured documentation, warranting the 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 states a specific verb ('Searches') and resource ('url_rewrite'), plus the fields returned. It clearly defines the tool's function and distinguishes it from the many get_* siblings by naming the target table and its purpose (debugging 404s, duplicate URLs, redirect loops).
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 lists three concrete debugging scenarios ('404s, duplicate URLs, or redirect loops') where the tool should be used. It does not state when not to use it or name alternatives, but the context is clear enough for an agent to select it appropriately among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which indicate a safe read operation. The description adds valuable behavioral context beyond annotations: 'Values are masked in output' and 'Does NOT decrypt encrypted values.' These disclose output handling and functional limitations, which meaningfully supplements the annotation profile. No contradiction.
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 deliver all essential information: purpose, scope, output masking, and a key limitation. Front-loaded with the primary action ('Flags'), followed by the constraint. No filler or 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 presence of an output schema (which handles return-value documentation), the description fully covers the tool's behavior: what it does, what it doesn't do (decrypt), and how output is handled (masked). Optional parameters are self-explanatory via the schema. An agent has everything needed to invoke it correctly.
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 both parameters ('profile' and 'magentoRoot') already well-described in the schema. The description adds no new parameter semantics, but the baseline of 3 applies because the schema already carries the burden. No additional value is needed.
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 clearly states the tool 'Flags core_config_data paths' that may contain unencrypted secrets, with a specific resource and verb. It distinguishes itself from all siblings, none of which audit plaintext secrets, and clarifies the scope (password/key/token paths). No ambiguity.
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 the tool is for auditing potential plaintext secrets, but it does not explicitly mention when to use it versus alternatives, nor does it state exclusion conditions. For example, it doesn't say 'use get_magento_config to retrieve encrypted values' or provide a comparator. Usage context is implicit but not made explicit, so a 3 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the operation's safety profile is fully covered. The description adds behavioral context by stating the ordering ('newest first') and that it returns 'recent' entries, which implies a limit based on the default parameter. This is useful but modest beyond the annotations.
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. The first sentence states the primary action and ordering, and the second sentence provides the use case and optional filter. No redundancy or extraneous details; the essential information is front-loaded.
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?
The tool has an output schema, so return values are covered. The description explains what the tool returns (recent entries ordered), how to filter, and when to use it. Standard parameters like profile and magentoRoot are already documented in the schema. Nothing needed for correct invocation is missing.
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 every parameter (limit, profile, magentoRoot, job_code_pattern) is already documented in the schema. The description mentions the job_code_pattern filter but adds no new meaning beyond what the schema provides. Baseline 3 applies here.
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 verb ('Returns'), the specific resource ('recent cron_schedule entries'), and the ordering ('newest first'). It also mentions the optional filter by job_code pattern. This clearly differentiates it from siblings like get_failed_cron_jobs, which target specific failure states rather than general recent entries.
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 guidance on when to use this tool: 'Use to debug stuck, missed, or error cron jobs.' It also notes the optional filter condition. However, it does not explicitly mention when not to use it or name alternatives like get_failed_cron_jobs, though the intended context is evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which covers the safety profile. The description adds the return content (codes and names) and a practical purpose, but does not elaborate on behavior like pagination, error handling, or performance. With strong annotations, this level of extra disclosure is acceptable; it's neither contradictory nor substantially richer.
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 filler. The first sentence states the primary output, and the second gives a concrete use case. It is front-loaded and every word earns its place.
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 rich annotations and the presence of an output schema, the description is fully adequate. It explains what the tool returns, why an agent would use it, and even hints at the mapping context. No critical information about calling this read-only informational tool is missing.
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 100% description coverage for both parameters (profile and magentoRoot), including their defaults and the override behavior. The tool description references the mapping purpose of the return, but does not add any extra semantics beyond what the schema already documents. Baseline 3 is appropriate given the complete 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 states a specific verb ('Returns') and a specific resource ('Magento store hierarchy'), enumerating its components (websites, store groups, store views) and their attributes (codes and names). This is distinct from any sibling tool, making the purpose unambiguous.
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 states when to use this tool: 'Use to map store_id / website_id when querying scoped data.' This gives a clear use case, though it does not mention when not to use it or name alternative tools. The context is sufficient for an agent to judge applicability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds the key behavior that it 'does not return row data,' which is important contextual information beyond the annotations. It also implies it expects a validated SELECT query, aligning with the safe, read-only nature. This adds value without contradicting annotations.
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 filler. The core action and effect are front-loaded in the first sentence, and the usage guidance is in the second. No redundant information. It is perfectly sized for a simple read-only tool.
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 read-only diagnostic tool that has annotations covering safety and an output schema (which presumably documents the execution plan result), the description sufficiently conveys the purpose and usage. It doesn't explain error scenarios or the exact return format, but those are adequately covered by the output schema and annotations. It could mention that it works only on SELECT/SHOW/etc., but the schema already does that. Overall, it's complete enough for an agent to decide when to call it.
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% – all four parameters (sql, query, profile, magentoRoot) have descriptions in the schema. The tool description does not add any parameter-specific information beyond what the schema already provides. The phrase 'validated SELECT query' mirrors the schema's restriction on SQL prefix. With full schema coverage, the baseline of 3 applies, and the description adds negligible value about parameters.
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 specific action ('Runs EXPLAIN'), the resource ('a validated SELECT query'), and the outcome ('shows the execution plan without returning row data'). This distinguishes it from siblings like execute_select_query and validate_select_query, even without naming them, because the verb 'EXPLAIN' and the explicit 'without returning row data' make the purpose unambiguous.
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 diagnose slow queries before running them on large Magento tables.' It implies this tool is for pre-execution diagnosis, not for actually running queries. However, it does not explicitly mention alternatives or when NOT to use this tool (e.g., when you need actual row data). Sibling tool names like execute_select_query hint at the distinction, but the description itself doesn't lay out exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds real behavioral value beyond those: the parent-child nesting structure for configurable/bundle items and the explicit absence of address data. No contradiction with annotations — 'Returns' aligns with readOnlyHint=true.
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 zero waste: the first front-loads the core function and the nesting nuance, the second delivers the exclusion and the sibling route. Every clause earns its place, and nothing is repeated from the schema or annotations.
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 an output schema exists (covering return structure) and rich annotations declare the safety profile, the description covers the essential behavioral nuance (nesting) and the key exclusion. Two minor gaps: the meaning of 'active' in the tool name is never defined, and 'configurable/bundle' nesting could use one clause on how it appears in output. Neither blocks correct invocation.
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 all three parameters (profile, quote_id, magentoRoot) are already documented in the schema with their own descriptions. The tool description adds no parameter-level detail beyond what the schema provides, which matches the baseline-3 case where the schema does the heavy lifting.
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?
States a specific verb+resource ('Returns quote_item rows for a quote_id') with precise scope, and adds the distinguishing nesting behavior ('parent-child nesting (configurable/bundle)'). It differentiates from siblings by explicitly naming what it does NOT return (quote addresses), which no sibling description ambiguity could survive.
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?
Gives an explicit exclusion with a named alternative: 'Does NOT return quote addresses — use execute_select_query on quote_address.' This routes the agent away from a tempting misuse. It lacks broader when-to-use framing (e.g., when debugging a quote's item breakdown), but the negative routing is concrete and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing safety. The description adds valuable behavioral context: the B2B requirement and the exclusion of requisition lists. It does not contradict annotations and enhances transparency regarding prerequisites and scope.
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 three concise sentences, each adding distinct value: purpose, requirement, and exclusion. It is front-loaded with the core action and avoids redundancy, making it easy for an agent to scan and understand.
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 read-only tool with an output schema and all optional parameters, the description covers the essential aspects: what it returns, a prerequisite, and a scope exclusion. It doesn't explain 'active' or sorting, but the output schema likely covers return structure, so the missing detail is minor.
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 each parameter is already documented in the schema. The description does not add additional parameter-level details beyond what the schema provides. Per calibration, this earns a baseline 3 since the schema carries the parameter context.
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 states a specific verb ('Returns'), resource ('active negotiable quotes'), and scope ('for a B2B company_id'). It also differentiates by explicitly excluding requisition lists, making it clear what the tool does not do. Though it doesn't name a sibling, the negative statement effectively distinguishes it from related quote 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 a clear prerequisite ('Requires Adobe Commerce B2B') and an exclusion ('Does NOT return requisition lists'), giving context for when the tool is applicable. However, it does not explicitly recommend this tool over alternatives or state when to use a different tool, so it falls just short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds a specific behavioral note: 'Does NOT consume messages', which is valuable context beyond the generic read-only hint. It also mentions the output grouping, though that is likely covered by the output schema. There is no contradiction, and the added non-consumption detail enhances 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?
The description is extremely concise: two sentences with no filler. The main purpose is front-loaded, followed by a critical caveat (non-consumption). Every word earns its place, and the structure is ideal for quick scanning by an 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?
Given the output schema exists, the description need not explain return values. The tool has three optional parameters, all documented in the schema. The description covers the core purpose and the key condition (non-RabbitMQ). It does not mention error conditions or pagination, but those are likely covered by the output schema or are acceptable omissions. The description is complete enough for effective 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 schema covers all parameters with detailed descriptions (100% coverage). The tool description itself does not add any parameter semantics beyond what the schema provides. Since the schema already explains each parameter thoroughly, a baseline score of 3 is appropriate here. The description doesn't need to repeat parameter info, and it doesn't.
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 function: 'Returns message counts grouped by queue name and status from internal DB queues'. It specifies the verb (returns), the resource (message counts), and the scope (internal DB queues) with a condition ('when not using RabbitMQ'). It also distinguishes itself by noting 'Does NOT consume messages', which clarifies it's a read operation. This effectively differentiates it from any potential message-consuming tools, even though none are in the sibling list.
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 on when to use the tool by mentioning 'when not using RabbitMQ', implying that other tools are used for RabbitMQ-based queues. However, it does not explicitly name alternative tools or state when not to use it. The reference to 'list_connection_profiles' in the parameter schema also gives contextual guidance, but this is outside the main description. Overall, usage guidance is clear but not as explicit as it could be.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the description doesn't need to repeat that. It adds valuable guidance about interpreting the result: 'static backend_type → query base entity table, not EAV value tables,' which clarifies a behavioral nuance beyond what annotations and schema provide.
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 lookup purpose and the key parameters. The query-guidance note is appended neatly without bloat, and every sentence 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?
With a full output schema and complete parameter descriptions, the description doesn't need to repeat those. It adds the crucial query guidance for interpreting backend_type, which is essential for effective use. The only minor gap is that the description implies both parameters are needed while the schema marks entity_type_code optional, but that's a schema concern more than a description 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 description coverage is 100%, so the schema already documents all parameters. The description adds the alias relationship between entity_type_code and entity_type, and it highlights the two most important parameters (entity_type_code and attribute_code) in the purpose statement, giving the agent better focus.
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 states a specific verb ('looks up'), a clear resource ('EAV attribute'), and the two key discriminators (entity_type_code and attribute_code). It immediately distinguishes from siblings like get_product_attributes by focusing on a single attribute lookup with backend_type guidance.
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 the primary use case—looking up a specific EAV attribute's metadata—but does not explicitly mention when to prefer this over alternative tools like get_product_attributes or when not to use it. There are no exclusions or alternative routing, so an agent must infer the appropriate context from the naming and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description reinforces this by explicitly stating 'Does NOT truncate tables', which adds clarity about its non-destructive nature beyond the generic annotations. It also frames it as a planning aid, indicating no side effects.
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?
A single sentence that conveys purpose, safety, and use context without any fluff. The information is front-loaded and complete.
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 an output schema (not shown) so return values need not be described. The description covers what the tool does, its non-destructive nature, and its intended use. It doesn't list which specific tables are 'common', but that's not essential for calling it. Given the annotations and schema, the description is sufficiently 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%, both 'profile' and 'magentoRoot' are well-documented in the schema. The description adds no additional parameter information, so baseline 3 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 explicitly states the tool 'returns sizes of common Magento log/visitor tables' and clarifies it is a 'planning aid for DB maintenance'. It is specific about the resource (log/visitor tables) and the action (returns sizes), distinguishing it from siblings like get_largest_tables which target all tables.
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 frames the tool as a 'planning aid for DB maintenance', implying it is for read-only analysis before cleanup. It does not explicitly contrast with alternatives or state when not to use it, but the context is clear. Lacks exclusions but provides a clear use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a useful behavioral detail beyond annotations: 'Row counts are approximate for InnoDB.' This warns about data precision and adds value without contradicting the annotations.
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 primary purpose is front-loaded, and the usage guidance follows immediately. Everything is relevant and to the point.
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 read-only listing tool with no required parameters and smooth schema coverage (100% param descriptions, output schema present), the description is complete enough. It covers storage metrics and the approximate-row-count caveat. It does not mention pagination or specific RETURN format, but the output schema likely covers that.
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%, and all three parameters have detailed descriptions (limit bounds, profile override, magentoRoot path). The description itself does not add additional meaning beyond what the schema already provides, so the baseline of 3 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 states a specific verb ('Returns'), a precise resource ('biggest Magento tables by storage size'), and the source ('INFORMATION_SCHEMA'). It also clarifies the metric (DATA + INDEX), which differentiates it from siblings like list_tables or get_heavy_log_tables that might focus on other criteria.
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 second sentence gives a clear when-to-use: 'Use to find bloated tables before running broad SELECTs.' This is actionable context. However, it does not mention any alternatives or explicitly state when not to use it, which would push to a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context on top: it returns value_status (set/empty/null) and an inherited default-scope value when scoped rows are empty. It does not contradict any annotation, and it gives the agent insight into edge-case output.
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 no filler. The first sentence front-loads the action, resource, and pattern; the second efficiently communicates the output behavior. Every piece of prose earns its place, and the text is compact enough for quick parsing.
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 an output schema present, the description does not need to detail return fields, and it doesn't. It covers the core behavior, the matching semantics, and the important inherited-value behavior. Minor omissions (e.g., whether multiple matches are returned, or implications of the profile parameter) are acceptable given the output schema and parameters are already documented elsewhere.
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 schema description coverage is 100%, and each parameter is already documented in detail (e.g., pathPattern is described as 'core_config_data path pattern (SQL LIKE)' with examples, and the alias is noted). The description essentially repeats the LIKE pattern and alias without adding new parameter semantics. Since the schema carries the burden, 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 states a specific verb ('Reads'), a concrete resource ('store configuration from core_config_data'), and a distinct mechanism ('path LIKE pattern'), which sharply distinguishes it from sibling tools. It also previews the return semantics (value_status and inherited default-scope value), so an agent knows exactly what to expect. None of the sibling names overlap with this config-read niche.
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 implies when to use it (when a store configuration value is needed from core_config_data) but does not explicitly state when not to use it or point to an alternative, since there is no closely competing sibling. It also notes the LIKE pattern behavior, which helps an agent decide if this is the right tool versus an exact-match query. Lacks an explicit 'use X instead when...' clause, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds behavioral value by specifying the output structure (table name, column name, and data type) and the pattern-matching semantics. It does not contradict annotations and provides context beyond the structured fields, though it omits details like pagination or performance considerations.
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 composed of three concise sentences: purpose with examples, return fields, and a follow-up recommendation. Every sentence serves a clear function without redundancy or filler. The most important information (what it does) is front-loaded, making it efficient for agent comprehension.
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 is a straightforward search function, and the description covers its core purpose, output, and a logical next step. An output schema exists, which likely documents the return structure in more detail, so the description does not need to repeat that. It adequately equips an agent to decide when to call this tool and what to expect, though it could mention result size limits or case sensitivity for perfect 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 100% description coverage, including examples and usage notes for all three parameters (pattern, profile, magentoRoot). The tool description adds no parameter-specific meaning beyond what the schema supplies, so it meets the baseline of 3 without exceeding it.
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 tables containing columns matching a name pattern, specifies the return fields (table name, column name, data type), and provides concrete examples. It explicitly differentiates itself from describe_table by recommending it as the next step for full column details, making its purpose unambiguous and distinct among siblings.
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 a clear directive to use describe_table next for full column details, which provides actionable follow-up guidance. It implies this tool is for coarse-grained column searches but does not explicitly state when not to use it or mention alternatives like find_order_by_increment_id, though the sibling context makes this less critical. The guidance is helpful but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds behavioral detail beyond annotations by specifying the internal parsing of block_id references and the reporting of counts, which are not conveyed by the annotations alone. This enriches understanding of what the tool does internally.
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 filler. The main action and scope are front-loaded in the first sentence, and the second sentence adds a practical output summary and the tool's value proposition. Every clause earns its place, making it concise and well-structured.
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 output schema exists (which explains return structure), the description already covers the key outputs: block identifiers, titles, is_active status, and active/inactive counts. The annotations cover safety, and the parameters are fully documented. Nothing an agent needs to decide whether to call the tool or interpret its results is missing.
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 all three parameters are fully documented in the schema. The description adds little beyond restating that the tool uses the identifier to load a page, which the schema already describes. It does not provide additional semantics or usage nuances for the parameters, so the 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 uses specific verbs: 'Loads', 'parses', 'reports' and names the exact resource (CMS page by identifier). It clearly distinguishes from siblings like get_cms_page (which fetches a page) by being an audit action that analyzes embedded blocks and returns counts, making its purpose unmistakable.
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 when to use it ('replaces manual SQL + regex parsing') and its scope (audit embedded blocks), but it does not explicitly name which sibling alternatives to avoid or when to prefer one over another. The context is clear enough for an agent to infer usage, but a direct reference to alternatives would elevate it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds only that it 'probes the database schema,' which is a minor behavioral detail (read-only probe) but does not disclose additional traits such as performance impact or potential errors. With annotations covering safety, the added value is limited.
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 fluff. The core purpose (what it detects and that it should run first) is front-loaded, and the structure is efficient and clear.
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?
The tool has an output schema, so return values are covered. Annotations cover safety and idempotency. The description explains what the tool detects and when to use it. Nothing essential is missing for an agent to call it correctly.
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 the baseline is 3. The description adds value by pointing to 'list_connection_profiles' for the profile parameter, which helps the agent determine valid values. It also clarifies the 'magentoRoot' default via env var or auto-discovery, which is context beyond the schema 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 function: 'Probes the database schema to detect OSS vs Commerce (row_id staging), MSI, and B2B availability.' It uses a specific verb ('probes') and resource ('database schema'), and explicitly lists what it detects. This distinguishes it from siblings like get_msi_stock_status or get_b2b_negotiable_quotes, which are specialized sub-queries.
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 'Run this first on an unfamiliar installation before using edition-specific tools,' which tells the agent exactly when to use it. However, it does not name specific alternative tools or provide explicit 'when not to use' conditions, though the guidance implicitly covers this.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive behavior, so the description's added value lies in disclosing the line-item limit (up to 50) and the performance benefit over raw SQL. This goes beyond annotations and is useful for an agent deciding whether to call it.
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 zero waste. The primary action is front-loaded, followed by a performance note and a routing alternative. Every sentence earns its place, and the structure is easy for an agent to parse quickly.
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?
For a simple lookup tool with one required parameter, full parameter documentation, an output schema, and safety annotations, this description is complete. It covers the key behavioral limit (50 items), differentiates from a sibling, and provides enough context for correct invocation without over-specifying.
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 all parameters, including an example for increment_id. The description adds minimal parameter-specific information beyond what's in the schema—it reiterates 'instead of raw SQL' and hints at scale, but doesn't need to compensate, 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?
States a specific verb and resource ('looks up a sales order by increment_id') and clarifies the return scope ('order header plus line items'). It also differentiates from raw SQL and the execute_select_query sibling for payment details, making its purpose unambiguous.
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 clear context: it is faster than manual JOINs and explicitly names execute_select_query on sales_order_payment as the alternative for payment details. However, it only covers one alternative use case and doesn't enumerate broader when-not-to-use scenarios, so it's strong but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive behavior. The description adds a non-obvious behavioral detail: the staging filter (updated_in) applied when present, which is valuable beyond what annotations provide. 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 sentences with zero waste. The primary purpose is front-loaded, followed by return fields and a behavioral nuance (staging filter). Every clause earns its place.
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 output schema exists, the description doesn't need to enumerate all return values, yet it highlights key fields and the staging behavior. The tool is simple (one required param) and the description covers all necessary operational aspects. Nothing critical is missing.
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 parameters (profile, identifier, magentoRoot) are fully documented there. The description only reiterates the identifier example, adding no new semantics beyond the schema. Baseline 3 is appropriate given full 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 uses a specific verb ('looks up'), identifies the resource ('CMS page'), and specifies the key ('identifier'), with a clarifying example. It also distinguishes itself from sibling tools like get_cms_block and audit_cms_page_blocks by focusing on page lookup with parsed block 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 clear context (lookup by identifier, staging filter) but does not explicitly name alternatives or state when NOT to use this tool. However, the purpose is so specific that an agent can infer when to choose it over related tools like get_cms_block or audit_cms_page_blocks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds value by specifying what the tool returns (host, database, latency, error details if unreachable), which is behavioral detail beyond the annotations. It does not contradict the annotations, and the described behavior is consistent with read-only 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 three concise sentences with zero fluff. It front-loads the primary purpose, then explains return details, and concludes with a usage recommendation. Every sentence earns its place, and the structure is clear and scannable.
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?
For a read-only diagnostic tool with two optional params and an output schema, the description covers purpose, return behavior, and usage context. It does not need to detail the output schema since that exists separately. Nothing an agent needs to call this tool correctly is missing.
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% — both parameters (profile and magentoRoot) are already described in the schema. The description does not add any parameter-specific meaning, but the baseline for high coverage is 3. No additional information is needed, so a 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 states a specific verb ('Tests') and resource ('database connectivity') plus the exact outputs (host, database, latency, error details). This clearly distinguishes it from siblings like get_indexer_status or list_connection_profiles, which have different targets. The wording is precise and unambiguous.
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 an explicit usage context: 'Use before running queries on an unfamiliar environment.' This tells an agent when to call the tool, but it does not explicitly mention alternatives or when not to use it. Still, the context is clear and non-misleading, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds that it reads from setup_module and filters by LIKE pattern, which is useful context beyond the annotations. It doesn't contradict any annotation and provides clear behavioral transparency about where data comes from.
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 fluff. It front-loads the core action (reads from setup_module), then adds the optional filter, and ends with the intended use case. Every word earns its place, making it highly efficient and easy to parse.
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?
The tool is simple, read-only, with an output schema present (so return values don't need to be explained). The description fully covers what it does and when to use it. There is no missing critical information for an agent to correctly invoke and interpret results.
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 each parameter well-described (profile, magentoRoot, module_pattern). The description adds example values and clarifies that module_pattern is a LIKE pattern and optional. However, this adds minimal additional meaning beyond the schema descriptions, so a 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 reads module schema/data versions from the setup_module table, specifying the exact resource and action. It also distinguishes itself from other read-only tools by focusing on module version verification, which is a specific use case. The verb 'Reads' is concrete and the target table is named.
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 to verify module upgrades applied correctly.' This tells the agent when to use the tool. However, it doesn't explicitly contrast with alternative tools (e.g., get_magento_config for configuration values), but the context is clear enough for a read-only version check. Minor gap since alternatives aren't named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds a valuable behavioral detail—that it does not return shipment line items—which is not captured in annotations. This extra clarity about the return scope goes beyond the structured fields.
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 filler: the first sentence states the core purpose, and the second adds a critical limitation. The key information is front-loaded, and every word earns its place.
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 that an output schema exists, the description sufficiently covers the tool's purpose and a key limitation. No critical information is missing for an agent to decide when to call this tool and what to expect from the return. The common parameters are also fully documented in the schema.
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%, and the description does not add any parameter-specific semantics beyond what the schema already documents. The schema fully describes 'increment_id', 'profile', and 'magentoRoot', so the description adds no extra value for parameters; 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 verb 'Returns' and the exact resource ('shipment tracking numbers and carriers') scoped to an order increment_id. It is specific and distinguishes itself from other unrelated sibling tools, leaving no ambiguity about what the tool does.
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 context (for an order increment_id) and a negative guideline ('Does NOT return shipment line items'), which implicitly tells an agent not to expect line items and to seek another tool if needed. However, it does not name an alternative, so it falls short of the explicit 'when-not/alternatives' criterion for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond annotations by specifying that it returns raw staging campaigns and does not apply staged values, and that it requires the Content Staging module. This informs the agent about the tool's behavioral 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 is three terse sentences that front-load the purpose ('Returns future staging campaigns affecting a product SKU') followed by the prerequisite and the key non-behavior. Every sentence earns its place, with no filler or repetition.
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 simplicity and the presence of a comprehensive output schema (which covers return format), the description fully covers what an agent needs to call it correctly: purpose, prerequisite, and a critical behavioral caveat. No essential information is missing.
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 all parameters (sku, profile, magentoRoot) are documented in the schema itself. The description adds no parameter-specific meaning beyond what the schema provides. However, the schema's sku description already includes a usage hint ('Use find_product_by_sku instead of guessing EAV table joins'), and the profile and magentoRoot descriptions are self-explanatory. Baseline 3 is appropriate since the schema does the heavy lifting.
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 states a specific verb ('Returns'), a specific resource ('future staging campaigns'), and a clear scope ('affecting a product SKU'). It also clarifies a key behavioral nuance ('Does NOT apply staged values'), which helps distinguish it from tools that apply staged changes. No sibling tool covers staging campaigns, so it is unambiguous.
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 prerequisite ('Requires Adobe Commerce Content Staging') and explicitly states what it does not do ('Does NOT apply staged values'). This gives the agent enough context to determine when the tool is appropriate, though it does not name explicit alternatives. The non-behavior effectively implies that if you need applied values, another tool is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the SHOW INDEX equivalence and use case context, but does not disclose further behavioral traits like error conditions or performance implications. With annotations present, this is a baseline level of added context.
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 three short sentences: it front-loads the core purpose, adds a use-case statement, and then provides a sibling alternative. Every sentence earns its place with no redundancy or filler.
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?
For a read-only, idempotent tool with a defined output schema and complete parameter documentation, the description covers all necessary context. It states what it returns, when to use it, and points to a sibling for related needs, making it sufficient for correct invocation.
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% for all three parameters, each already having descriptive text in the schema. The description provides no additional parameter-specific semantics beyond the schema, so the baseline score of 3 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 states it returns index definitions for a Magento table (SHOW INDEX), using a specific verb and resource. It clearly distinguishes from siblings like describe_table, which covers column-level details, leaving no ambiguity about what this tool does.
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?
It explicitly says the tool is useful for optimizing queries and understanding lookup paths, and it names an alternative (describe_table) for column-level details. This gives the agent a clear when-to-use and a specific case to delegate elsewhere.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the behavioral detail that the output is categorized and includes tags (OSS/MSI/B2B/Commerce), which enriches understanding beyond the annotations. No contradiction exists.
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 zero wasted words. The first sentence states the core function, and the second provides the usage trigger. Information is front-loaded and efficiently structured.
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?
For a simple tool with one optional parameter, an output schema, and annotations covering side effects, the description is complete. It explains what the tool returns (categorized list with tags) and when to use it. Nothing an agent needs to invoke it correctly is missing.
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% because the single 'tag' parameter has a full description in the schema ('Filter tools by edition tag. Omit for full catalog.') and a complete enum. The description itself adds no parameter-level insight, so the baseline score of 3 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 a specific verb ('Returns') and resource ('categorized catalog of all MCP tools'), and explicitly lists the tag categories. It distinguishes itself from sibling tools by being a meta-tool that catalogs other tools, which none of the siblings do. The purpose is unambiguous.
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 an explicit usage context: 'Use when unsure which tool fits a task.' While it doesn't explicitly state when not to use it, the guidance is clear and actionable. There are no alternative tools mentioned, but as a meta-tool, its use case is inherently distinct from the direct data-access siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds valuable behavioral context: that it runs without executing, and that it auto-appends a LIMIT preview to SELECT statements. This goes beyond the annotations and gives the agent a clear expectation of side-effect-free, non-mutating validation with a normalized output format. No contradictions to annotations.
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, tightly written with no filler. It front-loads the primary purpose (validation without execution), immediately follows with the key output detail (normalized SQL with auto LIMIT), and ends with a specific usage directive. Every word earns its place; it is concise without sacrificing informative value.
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?
For a validation tool with a rich output schema (present) and comprehensive safety annotations, the description covers the essential context: what it does, what it returns, and when to use it. The agent can correctly decide to invoke it before execute_select_query and can infer the input (SQL string). Given the output schema and annotations cover the remaining details, nothing critical is missing.
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% — every parameter (sql, limit, query) has a descriptive schema entry that covers meaning and constraints. The description's mention of 'auto LIMIT preview' reinforces the limit parameter's role but does not add new details beyond what the schema already provides. Since the schema fully documents the parameters, the description need not compensate, and the 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 states a specific action (validates SQL is read-only and safe to execute without running it), identifies the resource (SQL queries), and describes the primary output (normalized SQL with auto LIMIT preview). It distinguishes itself from execute_select_query by explicitly positioning itself as a pre-execution safety check, and from explain_select_query (which likely explains query plans) by focusing on validation. The verb-resource pairing is unique and clear.
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 to use this tool before execute_select_query on large or unfamiliar tables, providing a clear context and a specific sibling to pair with. It does not mention when not to use it or alternative tools like explain_select_query, but the primary use case is well articulated. The guidance is actionable and differentiated from execute_select_query, though it leaves some room for clarifying exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds genuine context beyond the annotations: the INFORMATION_SCHEMA source and the exact returned fields. It does not contradict any annotation (returning definitions aligns with readOnlyHint=true). It could note behavior on a nonexistent table, but the output schema likely covers that, so a 4 is fair.
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 with zero waste: purpose, usage trigger, and routing to an alternative. The core definition is front-loaded ahead of the guidance, and every sentence 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?
With a full output schema, detailed parameter descriptions, and safety annotations, the description covers the essential decision points: what it returns, when to use it, and which sibling handles the adjacent case. Could mention error behavior for missing tables, but the output schema and openWorldHint annotation cover the remaining surface for a simple describe-table 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%, so all three parameters (table, profile, magentoRoot) are already fully documented with examples and env-var fallbacks. The description adds nothing about parameter semantics beyond the schema, which is the expected baseline-3 situation when the schema does the heavy lifting.
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 states a specific verb (returns), a precise resource (column definitions with name, type, nullable, keys, default), and names the data source (INFORMATION_SCHEMA). The output field list distinguishes it cleanly from siblings like list_tables (which returns table names) and get_table_indexes (which returns indexes rather than column definitions), so an agent can pick it without opening the schema.
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 gives an explicit when-to-use signal ('Use before writing JOINs') and names the precise alternative with its selection condition ('Use list_tables if you don't know the exact table name'). This routes the agent correctly across two closely related schema tools with no inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds value by explaining the LIKE (partial-match) behavior and the static-column vs EAV distinction, which are behavioral nuances not present in annotations. However, it does not address openWorldHint (e.g., potential for unexpected result scope), but that is a minor gap given the annotations cover the critical safety aspects.
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 three sentences, front-loaded with the core function and immediately clarifying the alternative. Every sentence earns its place: the search action, the static-column note, and the routing to find_customer_by_email. No fluff or 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 output schema exists and annotations cover safety, the description is complete for an agent to call correctly. It explains the search semantics, the data source, and the alternative tool, leaving no critical missing information. The tool's parameters are all documented in the schema, and the description adds the needed behavioral context.
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 all four parameters have clear descriptions in the input schema. The description adds little param-specific value beyond the schema—it reinforces the name parameter's LIKE behavior but does not explain limit/profile/magentoRoot beyond what the schema already provides. Baseline 3 is appropriate since the schema does the heavy lifting.
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 searches customer_entity by firstname, lastname, or full name using LIKE, and explicitly differentiates from find_customer_by_email for exact email searches. It also adds the technical clarification that these are static columns, not EAV, which further pinpoints the exact resource and behavior.
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 directly names the alternative tool (find_customer_by_email) and the condition that selects it ('For exact email'). It implicitly communicates when to use this tool (when you have a name, including partial names) and provides clear context about the search type, leaving no ambiguity about when to invoke it versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds crucial context beyond these: it reads only the catalogrule_product_price index, meaning results are not live and may be stale, and it is scoped to today's prices. This behavioral trait is essential for correct interpretation and is not covered by the annotations. No contradiction exists.
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, zero filler. The key functional constraint (reads index, not live) is front-loaded and the temporal scope ('for today') is included. Every word earns its place.
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 low complexity, 5 parameters with only 1 required and defaults for others, and the presence of an output schema, the description covers the essential behavior and caveats. An agent knows exactly what to expect: a read-only, indexed, today-scoped price lookup. The lack of details about missing-rule handling is acceptable because the output schema likely covers the return shape, and the index-based note implies the behavior.
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, each parameter already has a detailed explanation (sku, profile, website_id, magentoRoot, customer_group_id). The description does not add additional semantic detail; it simply reiterates the role of sku, website, and customer group in the broader context. It adds no new information beyond the schema, 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 states a specific verb ('Returns indexed catalog rule price') and scopes it precisely to a SKU, website, customer group, and today. It also explicitly distinguishes what it does not do ('Does NOT calculate rules live'), making the tool's function unambiguous and clearly differentiated from potential alternatives.
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 guidance on when to use this tool: it reads the catalogrule_product_price index and is not a live calculator. This implies that the index may be stale and that live rule evaluation is out of scope, which helps an agent decide to use this instead of a hypothetical recalculation tool. However, it does not name an explicit alternative or describe the exact conditions under which this tool should be preferred over other index-based reads.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds the staging filter behavior and the fields returned, which are behavioral details not present in annotations. It doesn't mention pagination or error cases, but for a read-only lookup the given context is sufficient. The addition of the staging filter specifically addresses a non-obvious behavior, raising above baseline 3.
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 with no fluff. The core lookup behavior is stated first, followed by return fields and the staging filter, and the sibling pointer is at the end. Every sentence earns its place. The description is front-loaded with the most important action, and the sibling note is placed after primary usage, which is logical.
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 output schema exists (though not shown in full, the signal says 'Has output schema: true'), the description need not explain return values in detail. The annotations cover safety and idempotency. The description covers the core lookup, optional staging filter, and points to the sibling. For a read-only tool with zero required parameters, this is complete. No critical information is missing.
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 each parameter is already well-documented in the schema (e.g., 'block_id' says 'Use instead of identifier when known', 'profile' mentions override, 'magentoRoot' explains the default). The description itself adds little beyond the schema—it restates the identifier/block_id distinction but relies on the schema for detailed semantics. Baseline 3 is appropriate when the schema carries the parameter documentation.
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 looks up a CMS block by identifier or block_id, lists specific return fields (title, is_active, timestamps), mentions the staging filter, and distinguishes from audit_cms_page_blocks. The verb 'looks up' and the resource 'CMS block' are explicit, and the sibling differentiation is direct. This is a model example of purpose clarity.
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 clear usage context: when to look up a block directly (by identifier or ID) and when to use audit_cms_page_blocks instead ('For blocks embedded in a page'). It also implies the staging filter is automatically applied 'when present', alerting the agent to a contextual condition. No alternative is missed; the guidance is explicit and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the specific underlying table (catalog_product_super_link) and clarifies the scope of returned data (children only), which complements annotations without contradicting them. No side effects or auth details are needed given the read-only hint.
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 zero fluff. The main purpose is front-loaded, and the important caveat (does not return super attributes) is stated immediately, followed by the routing instruction. Every word earns its place.
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?
For a simple read-only lookup with a complete output schema, annotations covering safety, and full parameter documentation in the schema, the description succinctly explains what the tool does and what it excludes. Nothing an agent needs to call it correctly is missing.
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 all three parameters (sku, profile, magentoRoot) with helpful context (e.g., 'Use find_product_by_sku instead of guessing EAV table joins'). The tool description itself adds no additional parameter-level semantics beyond what the schema already provides, so the 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?
States a specific verb (Returns), resource (simple product children), and mechanism (via catalog_product_super_link). Explicitly distinguishes from what it does not return (super attributes) and names the sibling tool to use instead, making it unambiguous.
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 the negative case ('Does NOT return super attributes') and directly recommends the alternative (`execute_select_query` on `catalog_product_super_attribute`). This gives clear when-to-use and when-not-to-use guidance beyond the generic purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds useful context about the returned scope (last 24 hours, failed/stuck status) and explicitly confirms it is not a fixer, aligning with the non-destructive annotations. No contradiction.
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 the primary purpose, followed by a critical exclusion and alternative. Every word earns its place; no redundancy or 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?
For a simple read-only query tool with two optional parameters and an output schema, the description covers purpose, scope, and alternatives. The output schema handles return values, and annotations handle safety. Nothing needed for an agent to call it correctly is missing.
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 detailed descriptions for both 'profile' and 'magentoRoot'. The description does not mention parameters, but the schema already documents them sufficiently. Baseline 3 is appropriate since the description adds no extra parameter semantics beyond what the schema provides.
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 action ('Returns'), the resource ('cron_schedule jobs'), and the specific filter (failed or stuck) with a time window (last 24 hours). It also distinguishes itself from the sibling get_cron_schedule by noting that tool covers broader history, eliminating ambiguity.
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 what the tool does NOT do ('Does NOT fix crons') and points to an alternative ('use get_cron_schedule for broader history'). This gives clear guidance on when to choose this tool versus the sibling, leaving no inference needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the source (INFORMATION_SCHEMA) and the purpose, which is useful behavioral context beyond the annotations. It does not mention performance or failure modes, but given the annotations' strength, this is acceptable.
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. The primary action is front-loaded, followed by usage guidance and an alternative. Every word earns its place.
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?
The tool is simple, all parameters are documented in the schema, and an output schema exists (so return format is not the description's responsibility). The description provides sufficient context for an agent to call the tool correctly without missing 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 description coverage is 100%, so all three parameters (table, profile, magentoRoot) already have descriptions that explain their meaning and defaults. The description adds no extra parameter context, so with high coverage the 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?
States a specific verb ('Returns') and resource ('foreign key relationships for a table') and names the source ('from INFORMATION_SCHEMA'). It clearly distinguishes from siblings like describe_table and get_table_indexes, so an agent knows exactly what this tool does.
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 instructs when to use: 'Use before writing JOINs to understand referential links.' It also names the alternative for column details ('Use describe_table'), making the decision between tools unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds a valuable behavioral note that the tool does NOT trigger reindex, which is more specific than the abstract read-only hint. This goes beyond the annotations to clarify side-effect behavior, so a 4 is appropriate.
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 zero filler. The main purpose is front-loaded, the usage guidance is bundled, and the CLI alternative is provided without extra words. Every sentence earns its place.
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?
The tool has an output schema (so return values are defined), annotations for safety, and full schema coverage for parameters. The description adds the diagnostic intent and the no-trigger caveat. Nothing an agent needs to decide when to call or what to expect is missing.
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% and both parameters ('profile' and 'magentoRoot') are fully described in the schema. The tool description adds no parameter-level detail beyond what the schema already provides, so it hits the baseline of 3 – the schema carries the burden and does so completely.
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 states a specific verb ('Returns') and specific resources ('indexer_state and mview_state rows'). It clearly defines the tool's diagnostic purpose (stale indexers, 'reindex required', stuck mview consumers) and is distinct from any sibling tool in the list. Even without naming a sibling, the specificity leaves no ambiguity about what this tool does.
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?
It explicitly says when to use the tool ('Use to diagnose stale indexers, 'reindex required', or stuck mview consumers') and what it does NOT do ('Does NOT trigger reindex'). It also provides an alternative action (CLI: bin/magento indexer:reindex). This gives clear usage context and an exclusion, leaving no doubt about appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds the prerequisite 'Requires MSI tables', which is useful context beyond the annotations. It does not discuss error behavior or return format, but given the annotations cover safety and the output schema exists, the added prerequisite is sufficient to raise it above the baseline.
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 compact sentences. The first sentence states the result and scope, the second gives a prerequisite and an alternative. No wasted words, and the critical distinction is front-loaded.
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 has an output schema and comprehensive annotations, the description covers the essential purpose, prerequisite, and routing information. An agent can confidently call it for MSI stock queries and know when to use the legacy alternative. Nothing needed for proper invocation appears missing.
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 all four parameters with helpful details (e.g., sku guidance, profile override, stock_id default). The tool description adds 'per source' which hints at response granularity, but this is not directly tied to any parameter. The description adds minimal parameter-specific semantics beyond the schema, so it meets the 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 the verb 'Returns', specifies the resource ('MSI physical qty, reservation offset, and salable qty per source for a SKU'), and differentiates from the sibling find_product_by_sku by noting 'For legacy stock use find_product_by_sku'. This provides precise purpose and distinguishes it from alternatives.
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?
It explicitly states 'Requires MSI tables' as a prerequisite and directs legacy-stock users to find_product_by_sku. The schema for the sku param reinforces this by advising to use find_product_by_sku instead of guessing EAV joins. Clear guidance on 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is fully covered. The description adds valuable behavior beyond annotations: the 'store scope fallback' mechanism and the limitation to a fixed attribute subset. This gives the agent a clearer picture of runtime behavior without contradicting annotations.
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 the core purpose and attribute list, then the alternative tool reference. Every word earns its place; no filler or redundant detail. Excellent structure for an agent to quickly parse.
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?
With an output schema present (returns are documented), annotations covering safety, and the description specifying scope and limitations, nothing essential is missing. An agent has all the information needed to decide when to call and what to expect.
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 every parameter (sku, profile, store_id, magentoRoot) is already documented. The description adds no param-level semantics beyond what the schema provides; the attribute list is output behavior, not parameter guidance. Per the baseline rule, a 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?
States a specific verb ('Returns') and resource ('common EAV attributes') with an explicit list of attributes (name, price, status, visibility, url_key) and scope ('store scope fallback'). It also names the sibling get_eav_attribute to differentiate, making it clear this is not the catch-all attribute tool.
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 explicitly tells the agent when not to use this tool and what to use instead: 'Does NOT return all attributes — use get_eav_attribute + execute_select_query for custom attributes.' The schema further reinforces usage by advising find_product_by_sku for looking up SKUs. No ambiguity remains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety profile. The description adds behavioral nuance: it specifies the output scope (path and name) and explicitly negates the full tree behavior, which is beyond the annotation. This is valuable context that helps agents set expectations, so a 4 is justified.
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 filler. It front-loads the core purpose, then delivers the key exclusion and alternative. Every word earns its place, and it is easy to scan.
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?
For a simple read-only lookup tool, the description covers what is returned, what is not returned, and the alternative for the missing functionality. The output schema exists, so return structure is defined. Annotations cover safety, and parameters are documented in the schema. Nothing an agent needs to correctly invoke this tool is missing.
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%, meaning all three parameters (sku, profile, magentoRoot) are fully documented in the schema. The description itself does not add param-specific details, but because the schema already covers them, a baseline of 3 is appropriate. No additional semantic enrichment is necessary.
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 states a clear verb ('Returns') and specific resource ('category assignments for a product SKU') with details on what is included (path and name). It also explicitly differentiates from the full category tree by naming the alternative, so an agent can immediately distinguish this tool from sibling tools like execute_select_query.
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 directly states when not to use it ('Does NOT return full category tree') and points to the exact alternative ('use execute_select_query on catalog_category_entity for hierarchy'). Additionally, the sku parameter description provides further routing guidance ('Use find_product_by_sku instead of guessing EAV table joins'), making usage conditions explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it identifies the config file sources and explains that the active profile is derived from an environment variable. This enriches the agent's understanding of what the tool returns.
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 concise sentences, each contributing value: what the tool lists, the specific config sources, the active profile info, and a pointer to a related sibling. No redundant content; information is front-loaded and clear.
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 simplicity (no parameters, read-only, output schema provided), the description fully covers what an agent needs: the purpose, data sources, and how to follow up with connectivity verification. The existence of an output schema means return values don't need to be explained in the description.
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 zero parameters and the input schema is empty. Per the baseline for 0-parameter tools, a score of 4 is appropriate. The description doesn't add parameter information because there are none to document, which is consistent.
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 states a specific verb and resource: it lists database connection profiles from two explicit config file paths and shows the active profile from MAGENTO_SQL_PROFILE. This clearly distinguishes it from siblings like get_connection_status, which verifies connectivity rather than listing profiles.
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 recommends using get_connection_status to verify connectivity, giving clear context on when to use that alternative. While it doesn't state exclusions outright, the recommendation implies that this tool is for listing and inspecting profiles, not for checking live connection status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the core safety and variability are covered. The description adds value beyond annotations by explaining the filtering semantics (SQL LIKE pattern) and the fact that omitting the pattern lists all tables, which is useful behavioral context. It does not contradict annotations.
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 three sentences, each serving a distinct purpose: the main action (list tables with optional pattern), an example of the pattern, and the routing to two sibling tools. There is no fluff or redundant content, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values are documented elsewhere. The description covers the primary use case, the filter behavior, and explicitly directs to alternatives when a different intent is present. The remaining parameters are well-documented in the schema, and the annotation set provides the safety profile. Nothing an agent needs to call this tool correctly is missing.
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?
All three parameters (pattern, profile, magentoRoot) are fully described in the input schema (coverage 100%), so the description need not repeat them. The description's mention of the LIKE pattern matches the schema's description, adding no new meaning. A baseline of 3 is appropriate given the schema carries the parameter documentation.
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 states a specific verb ('Lists') and resource ('Magento database tables'), includes an optional filter example ('sales_%'), and explicitly differentiates from sibling tools by naming describe_table and search_columns as the right choices for column details or column-to-table lookup. An agent can immediately tell this tool apart from related list/search tools.
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?
It gives explicit when-to-use guidance: 'Use describe_table for column details. Use search_columns when you know a column name but not the table.' This directly tells the agent when to select an alternative, and the optional filter clarifies a legitimate use case for this tool. No guesswork is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds valuable behavioral context beyond annotations: it aggregates multiple sources into a single call, includes a 24-hour window for cron failures, and signals that the result is a summary rather than a deep dive. This is exactly the supplementary context the description should provide.
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 filler. The purpose and scope are front-loaded, and the caveat about deep dives is placed at the end. Every clause earns its place; ideal conciseness.
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?
The tool has an output schema (not shown, but indicated), so return-value details are redundant in the description. It has no required parameters, and the description fully covers what the health check inspects and its limitations. An agent can decide to invoke it correctly with no ambiguity.
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?
Both parameters (profile and magentoRoot) are fully described in the input schema (100% coverage), so the schema carries the semantic weight. The description does not add parameter-level detail, but it doesn't need to; the baseline of 3 is appropriate when the schema is complete.
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 a specific verb+resource ('run health check') and enumerates the concrete components: connection, edition detection, indexer issues, failed crons (24h), queue backlog summary. It also differentiates from siblings by framing itself as a 'single-call snapshot' and explicitly noting it does not replace individual diagnostic 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 provides a when-not instruction: 'Does NOT replace individual diagnostic tools for deep dives.' This implies the tool is for quick overviews and directs the agent toward sibling tools for detailed investigation. It does not name specific alternative tools, but the exclusion is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds valuable behavioral context: that it returns specific base-table fields and does NOT retrieve EAV attribute values, instead directing to other tools. This goes beyond annotations without contradicting them.
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 the primary purpose and return fields, immediately followed by the precise alternative for EAV cases. No filler or repetition; every sentence 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?
Given the tool's simplicity (a single-lookup by SKU), the description covers the essential behavior, return fields, and the limitation regarding EAV attributes, with a pointer to the correct alternative. The presence of an output schema covers return format details. It doesn't enumerate every edge case (e.g., SKU-not-found behavior), but given the output schema and annotations, the description is adequate and above average.
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 the baseline for parameter semantics is 3. The description text adds meaningful context for the sku parameter ('Use find_product_by_sku instead of guessing EAV table joins'), reinforcing its role as the primary lookup key. This increment justifies a score above baseline, though not the full 5 since no extra semantics are provided for the other two generic parameters (profile, magentoRoot).
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 states a specific verb ('looks up'), a precise resource ('catalog_product_entity by SKU'), and lists the returned fields (entity_id, type_id, attribute_set_id, timestamps). This clearly distinguishes it from other find_* tools (e.g., find_order_by_increment_id) by the target entity 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 instructs when not to use this tool and what to use instead: 'For EAV attribute values use execute_select_query...' and 'Use get_eav_attribute first to find backend_type.' Also reinforces the sku parameter usage with 'Use find_product_by_sku instead of guessing EAV table joins.' This provides clear context, exclusions, and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly and non-destructive behavior. The description adds valuable behavioral context beyond that: it clarifies the return scope (quote only, no items), specifies the uniqueness dimension (most recent active for a given email), and discloses the validation strictness (exact email required, partials rejected). It does not need to restate the annotations and adds useful operational 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 two sentences, with the core purpose in the first sentence and the essential caveat (no items, use sibling) in the second. Every sentence earns its place, and the most important information is front-loaded. The parameter descriptions are similarly tight and informative.
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 simplicity, the presence of an output schema, and annotations covering safety, the description fully equips an agent to call it correctly. It covers the return value, the exclusion of items, the alternative for items, and the email strictness. Nothing needed for correct invocation is missing.
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 the baseline is 3. The description adds meaningful semantics for the primary parameter email by explaining exact-match behavior and the rejection of partial strings, which is critical for correct invocation. Profile and magentoRoot are standard overrides whose descriptions already clarify their purpose. This enhancement justifies a 4.
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 states the function precisely: 'Returns the most recent active quote for a customer email.' It identifies the specific resource (quote), the filter (email), and the recency/status qualifiers. It also immediately differentiates from the sibling get_active_quote_items by explicitly stating what it does NOT return, making the tool's scope unambiguous.
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 gives explicit directional guidance: it tells the agent to use get_active_quote_items with the returned quote_id when quote items are needed, and the email parameter description reinforces the boundary by directing partial searches to find_customers_by_name and noting that partial strings are rejected. This is clear when-to-use and when-to-use-alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable security context by stating 'Password hash is never returned,' which is not implied by the annotations or schema. It also confirms the operation returns an order count summary, aligning with the output schema without repeating it.
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 short, dense sentences each contribute distinct value: purpose, return basis, sibling routing, and a security guarantee. There is no filler or redundancy, and the most important operational detail (exact match) is front-loaded.
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?
With an output schema present, return-value details are already covered. The description plus schema fully specify the input constraints, the alternative tool, the safety profile (via annotations), and the security guarantee. Nothing an agent needs to invoke or trust this tool is missing.
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 parameter semantics are fully documented in the schema, including the exact-match requirement and rejection of partial strings. The tool description does not add additional parameter-level meaning beyond what the schema already provides, so the baseline of 3 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 a specific action ('Exact email lookup') on a specific resource ('customer_entity') with a required precondition ('full valid email required'). It also explicitly names the sibling tool find_customers_by_name for partial name searches, providing immediate differentiation without needing to inspect schemas.
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 gives an explicit when-to-use condition (exact email match) and names the alternative for the not-this case ('For partial name search use find_customers_by_name'). This directly answers the routing question an agent would have between the two sibling lookup tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![magento-sql-mcp-server MCP server](https://glama.ai/mcp/servers/jigarkkarangiya/magento-sql-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/jigarkkarangiya/magento-sql-mcp-server)

Score Badge

Copy to your README.md:

[![magento-sql-mcp-server MCP server](https://glama.ai/mcp/servers/jigarkkarangiya/magento-sql-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/jigarkkarangiya/magento-sql-mcp-server)

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/jigarkkarangiya/magento-sql-mcp-server'

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