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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.