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

No annotations are supplied, so the description carries the full burden; it does disclose what is cleared (OpenCart and Journal3 caches) and the access requirement (SSH or DDEV), which is exactly the kind of auth/environment context the rubric credits. It stops short of stating side effects such as downtime, whether clearing is reversible, or whether the site must be reloaded afterward.

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, eleven words, with the action and scope front-loaded and the prerequisite following. Nothing is padded or repeated from the name/title.

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?

An output schema exists, so return values need not be explained, and the description covers purpose, cache scope, and the access prerequisite. For an unannotated, potentially disruptive cache-clear operation, a note about operational impact would make it fully complete.

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

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

The tool takes zero parameters, so the schema imposes nothing to document and the baseline for this dimension is 4. No additional parameter meaning is needed or missing.

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 ('Clear') and named resources ('OpenCart and Journal3 caches') plus the environment ('on VPS'), so an agent immediately knows what the tool does. It does not explicitly distinguish itself from the closest sibling, refresh_modifications, but the overlap risk is low.

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 'Requires SSH or DDEV' clause is a genuine execution prerequisite that tells the agent the conditions under which this tool can even run. However, it gives no when-to-use guidance relative to alternatives such as refresh_modifications, nor any when-not-to-use 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?

With no annotations, the description carries the full burden. It usefully discloses that the coupon is created enabled, starts today, and that uses_total=0 / uses_per_customer=0 mean unlimited — non-obvious semantics. However it omits mutation side effects, what happens with a duplicate or invalid code, and any permission requirements.

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 short lines, front-loaded with the action, then the two most non-obvious parameter semantics. No filler, though the fragmented line breaks after 'today.' read slightly awkwardly.

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?

Although an output schema exists (so return values need not be described), the tool has 10 parameters at 0% schema coverage and no annotations. A create operation with this much configuration surface needs far more description than is provided.

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 0% across 10 parameters, so the description must compensate. It only explains type, uses_total, and uses_per_customer, leaving code, name, discount, days_valid, free_shipping, logged_in_only, and min_order_total entirely undocumented.

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 ('Create a discount coupon') with the initial state ('enabled and valid from today'), which distinguishes it from update_coupon and get_coupons. It does not name those siblings explicitly, so sibling differentiation is implied rather than stated.

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?

There is no guidance on when to use this versus update_coupon, get_coupons, or get_vouchers, and no mention of prerequisites such as required fields or tenant/workspace context. Usage must be inferred from the name alone.

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?

No annotations are provided, so the description must carry behavioral burden. It discloses a meaningful filtering rule ('Excludes cancelled/failed/refunded orders from revenue'), which is non-obvious behavior. It stops short of describing auth requirements, rate limits, or caching, and defers return-shape details to the output schema.

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, front-loaded with the capability, then the routing cue, then the revenue exclusion rule. 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?

The tool has an output schema, so return values need not be described. The description covers capability, scope, and a key filtering rule, but omits what unit the revenue windows use, any timezone assumptions, and the meaning of the low_stock_threshold parameter.

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 0% and the single parameter low_stock_threshold has no description. The description mentions 'stock alerts' but does not explain that the threshold parameter controls them, leaving the parameter undocumented. A 4 reflects that only one optional parameter exists and it has a default, so the omission is low-impact.

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 opens with a specific verb+resource framing ('One-call store overview') and enumerates the exact content: revenue windows, order status breakdown, stock alerts, latest orders. It self-labels as the 'give me a store summary' tool, making it unambiguous against siblings like sales_summary or get_orders.

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 phrase 'The "give me a store summary" tool' provides a clear usage cue, and 'One-call' implies it replaces multiple granular calls. However, it does not explicitly name or exclude alternatives such as sales_summary or get_stock_report, which is the main gap 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?

No annotations and no explanation of whether this is safe, cached, or whether the category tree includes nested descendants, active/inactive categories, or store-scoped data. With an output schema present, return shape is not needed, but the description still lacks behavioral context like whether it traverses children or returns only direct children.

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 short imperative sentences, front-loaded with the action and immediately followed by the key parameter behavior. No 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 one-parameter read tool with an output schema, the description covers the main call pattern but omits important context: whether the tree includes nested descendants, whether inactive categories are returned, and what happens with invalid parent_id. Adequate minimum viable, but clear gaps remain.

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 0%, so the description carries the burden. It explains that parent_id=0 means top-level categories and implies parent_id selects children of a given category. This is meaningful semantics beyond the bare integer in the schema. It does not clarify whether the integer must reference an existing category ID or whether invalid IDs error.

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: get the category tree. Distinguishes from nearby tools like get_product, get_products, update_category, etc. It names the object (category tree) but does not explicitly call out its sibling relationships beyond resource specificity.

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 an implicit usage instruction: setting parent_id=0 returns top-level categories. It does not say when to use this tool versus alternatives like get_products or get_product_attributes, and there's no exclusion guidance beyond the parameter hint.

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?

With no annotations, the description carries the full behavioral burden. It does disclose the most important trait — results are silently filtered to enabled, unexpired coupons unless overridden — but says nothing about pagination, the 50-item default limit, or the read-only safety profile (merely implied by 'List').

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 short, front-loaded sentences with no filler; the core purpose leads and the filtering default follows. Slightly terse rather than wasteful — nothing needs cutting.

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?

An output schema exists, so return values need no explanation, and the description covers the key default-filtering behavior for a three-parameter list tool. The gap is the unexplained limit/pagination behavior, which an agent iterating results would want.

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 0%, so the description must compensate. It clarifies the meaning of 'search' (by code or name) and indirectly explains 'include_disabled' via the default-filter sentence, but the 'limit' parameter and its default of 50 remain unexplained in both description and schema.

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

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

States a specific verb and resource ('List discount coupons') and adds scope detail ('with usage counts', 'Search by code or name'). It is clearly a read/list operation distinct from create_coupon and update_coupon siblings, though it does not name those alternatives explicitly.

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 line 'Default: enabled, unexpired coupons only' usefully signals the default scope an agent will get, which is implied guidance for when this tool suffices. However, it never states when to reach for a sibling (create_coupon/update_coupon/get_vouchers) or when to broaden the filter, so usage is only implied.

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?

No annotations are provided, so the description carries the full behavioral burden. It does not state that this is a read-only lookup, whether results are paginated, how matching works, or what happens with an empty search string.

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 efficient sentence with no filler. However, brevity here contributes to the under-specification rather than being purely a virtue.

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?

An output schema exists so return values need not be described, but the tool has no annotations, no documented params in the schema, and no usage guidance, so an agent lacks enough context to invoke it confidently.

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 0%, so the description must compensate. It clarifies that 'search' matches against name or email, which adds real meaning, but the 'limit' parameter (default 20) is left entirely unexplained.

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 (Search) and resource (customers) plus the two searchable fields. It is clear enough to distinguish from update_product or get_orders siblings, though it never explicitly names an alternative.

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

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

No guidance on when to use this versus other retrieval tools (query, run_sql, get_orders). Usage is only implied by the word 'Search' and the named fields.

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?

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only list via 'List', but discloses nothing about permissions, pagination, result size, or whether disabled/uninstalled extensions are included — details an agent may need before calling.

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 front-loaded sentence with the verb and resource up front and no filler. It is appropriately sized for a parameterless list 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?

The tool is a simple, parameterless read with an output schema that already documents the return shape, so the description need not explain return values. The main remaining gap is usage positioning against the many sibling list tools.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to clarify beyond the empty schema, and it does not mislead about inputs.

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: 'List installed OpenCart extensions.' The resource 'extensions' is distinct from nearby siblings like get_modules, get_modifications, and get_settings, though the description never explicitly contrasts them, so sibling differentiation is left to the agent's inference.

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

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

No when-to-use guidance is given. With many similarly-named list tools in the sibling set (get_modules, get_modifications, get_information_pages), an explicit note such as 'use this when inspecting installed extensions rather than modules' would have been valuable; the description offers none.

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?

With no annotations, the description carries the full burden and does well: it discloses the head/tail default, the 2000-line cap, grep's 50k-line scan window with from_end, and the SSH/DDEV prerequisite. It omits error behavior for missing/unreadable paths and does not explicitly confirm the operation is non-mutating.

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?

Purpose is front-loaded in sentence one, followed by compact behavior rules ordered by parameter relevance. Every sentence conveys a non-obvious constraint; none is 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?

An output schema exists, so return-value shape need not be described. Given a 4-param read tool with no annotations, the description covers scoping, defaults, caps, performance trade-offs, and prerequisites — 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 0%, so the description must compensate, and it does for all four parameters: path resolution rules, grep as fixed substring (not regex) with its scan semantics, from_end's tail behavior, and max_lines' hard cap. This is meaning well beyond the bare types in the schema.

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

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

Opening sentence states a specific verb (Read) plus resource (file) plus the scope constraint (VPS, path relative to OpenCart root unless absolute). It is clearly distinguishable from the write_file sibling, which mutates, whereas this reads.

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 a concrete recommendation on when to use from_end=True ('preferred for large logs such as error.log') and warns when grep will be slow. It does not, however, name an alternative tool for reading large logs or state exclusions, so it stops short of full when/when-not routing.

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?

With no annotations, the description carries the full behavioral burden, yet it only implies a read via 'Get' and says nothing about permissions, error behavior for an invalid ID, or side effects. 'Full content' hints at return scope, but the output schema already covers that, so no meaningful behavioral trait is added.

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 front-loaded sentence with no filler; the verb and resource appear first and nothing is redundant. Appropriately sized for a one-parameter read 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?

The presence of an output schema means return values need not be explained, and the description covers the basic operation and its ID input. However, for a tool with zero annotation coverage it omits usage context and error/prerequisite information that would make it fully self-sufficient.

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

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

Schema description coverage is 0%, so the description must compensate for the single integer parameter. 'By ID' confirms the parameter is an identifier, but it adds no format, source, or range detail beyond the schema's name and type, leaving the parameter largely undocumented.

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 ('Get') and resource ('full content of a single information/CMS page') and the 'single' qualifier implicitly distinguishes it from the plural list sibling get_information_pages. It stops short of explicitly naming that sibling, so an agent still has to infer the routing rule.

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?

There is no guidance on when to use this tool versus get_information_pages or update_information, nor any prerequisite such as needing an existing ID. The description only says what it does, leaving the selection decision 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?

No annotations are provided, so the description carries the burden. It usefully discloses the return shape ('title and content preview') and the search target ('title text'), but says nothing about pagination, result limits, whether the search is a substring/prefix match, or that content is truncated to a preview rather than full body. Partial disclosure only.

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 short sentences, front-loaded with the resource and return shape, with the search behavior appended. No filler, though the second sentence is terse enough to feel slightly clipped rather than 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?

An output schema exists, so return values need not be explained further, and the description covers what the tool lists and how to filter. The remaining gap is behavioral detail (pagination, match semantics) rather than core completeness.

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 0% and the single 'search' parameter has no description in the schema. The description compensates by stating 'Search by title text', which tells the agent what the parameter matches against, but omits matching behavior (substring vs exact), case sensitivity, and what an empty/default value returns.

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 ('List') and resource ('CMS/information pages') with examples of what those pages are, and distinguishes itself from the singular sibling get_information_page by the plural/listing framing. It does not explicitly name that sibling as the alternative, so differentiation is implied rather than stated.

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?

Usage is implied by the description ('list pages ... search by title text'), but there is no explicit guidance on when to use this versus get_information_page for a single page or versus get_seo_urls/get_categories for related lookups. Nothing states prerequisites or 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?

With no annotations, the description carries the full behavioral burden. It usefully warns that the result is 'full JSON config' and 'can be large for complex modules', but it does not state read-only status, permission requirements, or error behavior.

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 tight sentences, front-loaded with the core action and followed by a useful size warning. No sentence is wasted.

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 single-parameter read tool with an output schema, the description covers the essential action and a relevant output-size caveat. It is slightly thin on parameter format and alternatives, but it is largely complete for this complexity level.

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 0%, so the description must compensate for the undocumented module_id parameter. It only says 'by ID', which adds minimal meaning beyond the parameter name and type already present in the schema.

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

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

The description states a specific verb and resource: 'Get full Journal3 module data'. It also scopes the operation to 'a single module by ID', which clearly distinguishes it from the sibling list tool get_modules.

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?

Usage is implied by 'for a single module by ID', so an agent can infer this is for fetching one known module. However, the description never explicitly says when to use this instead of get_modules or update_j3_module, and it offers no when-not 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?

No annotations are provided, so the description carries the full behavioral burden. It does not disclose whether results are paginated, permissions required, or read-only nature, beyond the implied read from 'Get'.

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 short sentences, front-loaded with the core action and followed by the filter semantics. Minimal but complete for the stated scope.

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?

An output schema exists, so return values need not be explained. For a one-param read tool, the description covers what it fetches and how to filter, though sibling differentiation and permission context are absent.

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 0% and only one optional parameter exists with a default of empty string. The description explains that 'pattern' is an SQL LIKE pattern for setting_name, adding essential meaning the schema entirely lacks.

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 (Get) and resource (Journal3 theme settings), and the second sentence narrows scope to a filterable retrieval. It is clearly distinguishable from siblings like get_settings and get_j3_skin_settings.

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

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

The description implies usage via the pattern filter (retrieve a subset by name), but does not say when to use this versus get_settings or get_j3_skin_settings. No when-not guidance is provided.

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?

No annotations are supplied, so the description carries the burden. 'Get' implies a read-only operation, which is the key safety signal, but there is no mention of permissions, whether skin_id missing means 'all skins', or any pagination/rate behavior.

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 short sentences, front-loaded with the resource and immediately followed by the filtering rule. No 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?

An output schema exists, so return values need not be described, and this is a low-complexity read tool. However, the undocumented skin_id parameter and absent usage context leave the definition only minimally complete.

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

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

Schema coverage is 0%, so the description must compensate. It explains that 'pattern' filters by setting_name using SQL LIKE semantics, which is genuinely useful, but 'skin_id' (default 1) is never mentioned, leaving half the parameters undocumented anywhere.

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 (Get) and resource (Journal3 skin settings), which clearly separates it from the sibling get_j3_settings (global settings) and the update_j3_skin_setting mutation. It stops short of explicitly naming the sibling it is not, so it lands at 4 rather than 5.

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

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

No indication of when to use this versus get_j3_settings, get_settings, or the update_* variants, and no prerequisites mentioned. The only guidance is implicit in the resource name.

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?

No annotations are provided, so the description carries the full behavioral burden. It only states that all modifications are listed with status; it does not explicitly confirm read-only safety, explain pagination, or describe scope limitations beyond the word 'all'.

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 short sentence with the resource and returned field front-loaded. Nothing is wasted and nothing needs restructuring.

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, takes no parameters, and has an output schema, so the description is nearly sufficient for invocation. However, it omits any usage context or relation to the refresh_modifications sibling, leaving a small but real gap for agent routing.

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?

There are zero parameters and schema description coverage is 100%, so the baseline is 4. The description does not need to explain parameter syntax, and it does not contradict the empty schema.

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

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

States a specific verb ('List') and resource ('OCMOD modifications') plus returned field scope ('with status'), which is clear enough to distinguish it from refresh_modifications. It does not explicitly name or contrast with any sibling, so it stops short of a 5.

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

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

No when-to-use guidance, no prerequisites, and no mention of the sibling refresh_modifications or any alternative. The agent can infer this is a read/list operation, but nothing directs selection between this and related retrieval 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?

No annotations are provided, so the description carries the full burden. It does disclose the meaningful behavioral detail that search operates over module_data content, and the read-only listing nature is implicit in "List", but it says nothing about result limits, pagination, or how partial matching behaves.

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 short sentences, no filler, with the core listing action front-loaded ahead of the filter details. Slightly terse for the information it must carry, but nothing is wasted.

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?

An output schema exists, so return values need not be described, and both input parameters receive at least some semantic treatment. What remains missing (match behavior, result size) is minor for a simple read-only listing 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 0%, so the description must compensate, and it does reasonably well: module_type is given concrete example values ('products', 'slider', 'product_tabs') and search is scoped to module_data content. It stops short of describing match semantics or the empty-string defaults.

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 ("List Journal3 modules") and names the filterable dimension, so the agent knows exactly what it retrieves. It does not, however, distinguish itself from the singular sibling get_j3_module, which is the main nearby 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?

Usage is implied by the two filters (type filtering, content search), but there is no explicit when-to-use statement or mention of alternatives such as get_j3_module for a single module. An agent can infer the use case but gets no routing 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. For a read operation, it does not state whether it requires authentication, whether there are any rate limits, or what happens if the order is not found. It contradicts no annotations but is essentially silent on behavior.

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, front-loaded sentence that is appropriately sized and contains no filler. It efficiently communicates the tool's core function.

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 (which covers return values), the description's job is to cover purpose, usage, and parameter semantics. It fails on usage and parameter semantics, and provides no behavioral context for a read tool with no annotations. It is inadequate for safe and 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 0%, so the description must compensate. The description does not mention the order_id parameter at all, nor its type or format. It adds no semantic meaning beyond the parameter name.

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 (Get) and resource (order), and specifies the scope of the return data ('full order details including line items and totals'). It is distinguishable from the sibling get_orders (plural, list) by the singular name, but the description itself does not explicitly call out this relationship.

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

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

The description provides no guidance on when to use this tool versus alternatives like get_orders or get_order_statuses. It merely states what it does, leaving the agent to infer that this is for fetching a single order by ID.

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?

No annotations are provided, so the description carries the full burden, but 'Get' clearly implies a read operation and the default window ('last 30 days, 20 orders') is genuinely useful behavioral context. It omits sorting order, whether results are paginated, and any auth or rate-limit constraints, so coverage is only moderate.

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 short, front-loaded fragments with no filler: purpose first, then the filter option, then the defaults. Every clause carries information an agent can act on.

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?

An output schema exists, so return values need no explanation, and the defaults are covered. However, with zero annotation coverage and zero schema descriptions, gaps remain around valid status values, result ordering, and pagination limits, which a caller would need.

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 0%, so the description must compensate. It does map all three parameters loosely (status to a status name with examples, days to 'last 30 days', limit to '20 orders'), but never states that limit is a maximum result count, gives no cap or range, and does not explain how status values are matched.

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 ('Get recent orders') and scopes it to recency, which implicitly separates it from the singular get_order sibling. It does not name that sibling explicitly, so differentiation still requires the agent to infer it from the plural/resource wording.

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 tells the agent it can filter by status name and gives example values, which implies the intended usage context. It never states when to choose this over get_order (single order) or how to obtain valid status names (get_order_statuses), so routing guidance is only partial.

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?

No annotations exist, but this is a 0-parameter read-only enumeration, so most behavioral risk is inherently absent. 'List all' conveys the read-only, exhaustive scope, though it says nothing about ordering, filtering, or caching.

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 front-loaded sentence with zero filler; every word (verb, scope, returned field) 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 0-param reference lookup with an output schema covering the return shape, the description is nearly complete. Only the lack of routing guidance against sibling list/read tools keeps it from full marks.

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

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

The tool takes zero parameters, so the baseline is 4. There is no parameter surface for the description to explain.

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 (List) and resource (order statuses) and notes the returned IDs. It is distinguishable from write-oriented siblings like update_order_status, but it does not explicitly differentiate itself from other read tools such as get_order or get_orders.

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

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

No when-to-use guidance or alternatives are given. An agent has to infer that this is a lookup/reference call rather than something covered by get_orders or get_order.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses what data comes back (images, options, attributes) but says nothing about auth requirements, behavior when the product_id is invalid, or any limits, leaving key operational traits undisclosed.

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?

One compact sentence with the resource and returned fields front-loaded and no wasted words. It is efficient, though almost too terse given the missing context elsewhere.

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?

An output schema exists, so return values need not be enumerated, and the description is adequate to identify the tool's basic function. However, with no annotations and no description coverage of the lone parameter, it stops just short of fully informing an agent for a simple lookup 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 0% and the single parameter product_id is never mentioned in the description. The phrase 'a single product' implies an identifier must be supplied, but no format, type, or key name is conveyed beyond what the raw schema shows.

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 (get) and resource (product) and scopes it to 'a single product', which implicitly distinguishes it from the sibling get_products list tool. It also enumerates what is returned (images, options, attributes), though it does not name the sibling it is not.

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?

There is no explicit guidance on when to use this versus get_products or get_product_attributes. The word 'single' hints at the list-vs-item distinction, but no alternative or condition is stated, so usage must be inferred.

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?

No annotations are provided, so the description carries the burden, but 'Get' plus 'all attributes' adequately signals a safe, non-mutating read with full-attribute scope. It does not mention permissions, whether a missing product errors or returns empty, or pagination, which leaves residual ambiguity for a zero-annotation tool.

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

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

One short sentence, front-loaded with the operation and finished with a compact illustrative list. Nothing is wasted, though the parenthetical examples slightly dilute the core statement.

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?

An output schema exists, so return values need not be described. However, with no annotations, an undocumented parameter, and no routing versus get_product/get_products, the definition is only minimally complete for correct selection and 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 0% and the single product_id parameter is undocumented in both schema and description. The phrase 'for a product' only implies the identifier exists; it adds no format, range, or resolution detail (e.g. internal ID vs SKU).

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 ('Get all attributes for a product') and illustrates the kind of data returned (CAS number, molecular weight, storage). It is distinguishable from generic siblings like get_product, though it never explicitly says how it differs from get_product or get_products.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as get_product or get_products. The agent must infer the invocation context entirely from the name.

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?

No annotations, so the description carries full burden. It usefully discloses that full HTML descriptions are excluded unless include_description=True, which is genuine behavioral context. However, it says nothing about pagination limits, default page size, auth/permissions, or result truncation.

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, front-loaded sentences with no filler. The return-data summary leads, then search/filter/flag mechanics follow. Efficient, though slightly clipped.

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 explanation isn't required. The description covers the meaningful parameters and the description-inclusion tradeoff, leaving only the limit parameter and its pagination behavior unaddressed.

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 0%, so the description must carry all parameter meaning. It explains search, category_id, and include_description semantics well, but the 'limit' parameter (default 50) is entirely undocumented in both schema and 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?

States a clear verb ('List') and resource ('products'), plus what data comes back (stock, prices, SEO). It's distinguishable from the singular 'get_product' sibling by implication, though it doesn't explicitly name the alternative.

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 implied usage ('Search by name', 'filter by category_id') but never states when to use this vs get_product, get_stock_report, or get_product_attributes. The agent must infer routing across a crowded product-tool sibling set.

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?

No annotations are provided, so the description carries the full behavioral burden. It doesn't say whether the result is paginated, whether an empty query_pattern returns everything, or what permissions are needed. The single sentence gives no behavioral context at all.

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 short sentences, front-loaded with the purpose before the filter example. Efficient and without waste, though terse to the point of under-specification.

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 retrieval tool with an undocumented parameter, no annotations, and only a hint at output shape (output schema exists, so return values need not be described), the description is too thin. It leaves the agent guessing about matching semantics, empty-parameter behavior, and result ordering.

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 0%, so the description must compensate, but it only offers a single example pattern. It doesn't explain the matching semantics (LIKE, prefix, exact?), the meaning of the empty-string default, or valid pattern syntax. One short example is insufficient for a 0%-coverage parameter.

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

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

States a specific verb (Get) and resource (SEO URL mappings), and the sibling set makes the resource distinguishable from update_seo_url. However, it doesn't explain what an 'SEO URL mapping' contains or why an agent would fetch one, so it falls short of a 5.

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 example pattern ('product_id=%') hints at a filtered retrieval scenario, implicitly suggesting use when you need URLs matching a pattern. But there is no statement of when to use this versus alternatives, and the exclusion of update_seo_url (the write sibling) is only inferable from the name.

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?

No annotations are provided, so the description must carry the full behavioral burden. While 'Get' implies a read, the description does not explicitly state read-only safety, auth requirements, rate limits, or side effects; it only describes the key-pattern matching behavior.

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 then filter details. There is no redundant text, and every sentence contributes directly to understanding the 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?

An output schema exists, so return values need not be described. The description covers purpose and parameter filtering, but it omits when-to-use guidance and read-only/auth context for a tool that has no annotations.

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 0%, so the description must compensate for both parameters. It explains that group filters by group (e.g. 'config') and key supports a SQL LIKE pattern, adding useful meaning, though it does not clarify that empty defaults likely mean no filter.

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 ('Get') and resource ('OpenCart settings'), and describes the filtering capability. However, it does not name or distinguish sibling tools such as get_j3_settings or get_j3_skin_settings, so sibling differentiation is left implicit.

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

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

The description explains available filters but gives no when-to-use guidance, alternatives, or prerequisites. An agent must infer that this is the default settings getter rather than one of the J3-specific or generic query 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?

No annotations are provided, so the description carries the full burden. It implies a read-only operation but does not state that explicitly, nor does it describe pagination, rate limits, or the format of the report. The sorting behavior is a useful trait, but overall behavioral disclosure is minimal.

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

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

A single, efficient sentence that front-loads the core action and includes key scoping details (active products, sorting). No wasted words.

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

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

An output schema exists, so return values need not be explained. However, for a report tool with no annotations and an undocumented limit parameter, the description is somewhat incomplete: it doesn't clarify what the limit applies to or whether results are paginated. The sorting detail is helpful but not enough to fully compensate.

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 has 0% description coverage for the single parameter 'limit'. The description does not mention the limit parameter or what it controls. However, since there is only one optional parameter with a default, and the description adds some context via sorting and scope, a baseline of 3 is appropriate as the schema still provides type and default.

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

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

States a clear verb (get) and resource (stock levels/report) with scope (active products) and ordering (sorted by quantity lowest first). Distinguishes itself from sibling tools like get_products or get_product by focusing specifically on stock levels, though it doesn't explicitly name 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?

No guidance on when to use this tool versus alternatives like get_products or get_product. There is no mention of use cases, prerequisites, or 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?

With no annotations, the description carries the full behavioral burden, and it does add one genuinely useful trait: the install prefix is applied automatically if omitted. It does not state that the operation is read-only, what happens for an unknown table, or any error/auth behavior.

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 short sentences, the core purpose front-loaded and the prefix caveat immediately after. Nothing is padded and every sentence carries information.

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

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

An output schema exists, so return values need not be described. For a one-parameter inspection tool the description covers purpose and the main input quirk, leaving only minor gaps such as read-only status and failure 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?

Schema description coverage is 0% and the single 'table' parameter has no schema-level detail, so the description must compensate. It does so meaningfully by explaining that the 'oc_'-style prefix is added automatically when missing, which is non-obvious behavior an agent needs.

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 concrete verb and resource ('Show columns for an OpenCart table'), which is enough to distinguish it from list_tables or query at a glance. It stops short of explicitly naming or contrasting the siblings that could also inspect 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?

There is no when-to-use guidance, no mention of alternatives such as list_tables or run_sql, and no stated prerequisites. Usage is only inferable from the verb, so an agent gets no routing help.

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?

No annotations, so the description carries the disclosure burden. "List" implies a safe read and the enumerated fields hint at return content, but it says nothing about scope, filtering, pagination limited by limit, or whether results are tenant-scoped. A 3 reflects the minimal implication of read-only listing without explicit confirmation.

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?

One efficient, front-loaded sentence with no waste. Slightly terse given the missing behavioral and parameter context.

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?

An output schema exists, so return-value explanation is unnecessary. However, with no annotations and no parameter documentation, the description is only minimally complete for a list tool; it omits filtering, scope, and limit semantics.

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 0% for the single limit parameter, so the description could have compensated but does not mention it. The description adds no syntax or default details beyond what the schema shows, leaving the baseline of 3 for a one-param tool.

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 (List) and resource (gift vouchers) and names the returned fields (amount, sender/recipient, status). It is distinguishable from neighbors like get_coupons, but does not explicitly contrast with that closely related sibling.

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

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

No when-to-use, when-not-to-use, or alternative guidance. The agent gets no signal about how this differs from get_coupons or whether filters exist; it must infer usage entirely.

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?

No annotations are provided, so the description carries the burden. It usefully discloses a non-obvious default behavior (returns all OpenCart tables using the detected prefix), which is real added value. However it omits whether this is read-only (implied), permissions required, and how results are ordered or capped.

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 short sentences, front-loaded with the action and immediately followed by the default scoping behavior. Zero 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?

An output schema exists, so return values need not be described. But for a listing tool with an undocumented filter parameter and no sibling routing, the description leaves the pattern format and the read-only/prefix assumptions partly unresolved.

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 0% and the single 'pattern' parameter is documented only as 'matching pattern'. No syntax is given — LIKE wildcards, regex, or glob — so an agent cannot construct a valid filter without guessing. The description gestures at the parameter without compensating for the schema gap.

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 ('List database tables') plus a scoping mechanism (pattern matching). It is distinguishable from siblings like get_table_schema and query, though it doesn't explicitly name them. Clear but not maximally differentiated.

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

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

No guidance on when to use this versus get_table_schema, query, or run_sql, all of which touch the same database. The 'Default: all OpenCart tables' note hints at a use case but never states when/when-not to call it. An agent must infer the routing.

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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the important safety trait — read-only, SELECT statements only — which is real value beyond the schema, but it omits anything about result-size limits, timeouts, required privileges, or cost of arbitrary queries.

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 short sentences with zero filler, and the core capability plus its constraint are front-loaded ahead of the routing hint. Nothing is redundant with structured fields.

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?

An output schema exists, so return values need not be explained, and the read-only constraint is stated. What is missing is disambiguation from the 'run_sql' sibling and any note on query limits or error behavior — meaningful gaps for a tool whose only input is free-form SQL.

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?

There is a single 'sql' parameter with 0% schema description coverage, so the description must compensate. 'Only SELECT statements allowed' adds a genuine constraint on that parameter's content, but it offers no dialect, table/column naming, or formatting guidance the agent would need to write a working query.

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 ('Execute a read-only SQL query') with the key constraint (SELECT only). It partially differentiates via 'custom queries not covered by other tools', but it never distinguishes itself from the near-identical sibling 'run_sql', leaving an obvious ambiguity unresolved.

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?

'Use this for custom queries not covered by other tools' gives implied usage context, pointing the agent away from the purpose-built getters. However, it gives no when-not guidance and ignores the fact that a sibling named 'run_sql' appears to do the same thing, so the routing decision is left ambiguous.

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?

With no annotations, the description carries the burden and does well: it discloses the exact mutation effect (cache cleared, unmodified files served) and a hard limitation (no full recompile). It does not state permissions or whether the action is safe/idempotent, but it covers the most important behavioral trait for a cache-clearing tool.

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

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

Two sentences, no waste; the primary effect is front-loaded and the caveat immediately follows. 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?

Complete for a no-argument, no-annotation mutation: it explains what is cleared, what the user must do next, and what the tool cannot do. Output schema exists, so no return-value explanation is needed.

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?

Zero parameters, so baseline is 4. The description adds no parameter info because there are none to describe.

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 (Clear) and resource (OCMOD modification cache) with a clear effect (serves unmodified files). Distinguishes itself from sibling 'clear_cache' and 'get_modifications' by naming exactly which cache and what it does not do.

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 follow-up step needed (Admin > Extensions > Modifications > Refresh) and that this tool cannot do it, preventing misuse. This is when-to-use and what-not-to-expect guidance in two sentences.

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?

With no annotations, the description carries the full burden. It does disclose that this mutates the database directly and is limited to write statements, which is valuable, but it omits permissions required, whether DDL is allowed, transaction/reversibility behavior, and blast radius.

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 short sentences, zero waste, with the destructive nature front-loaded before the caution. Nothing extraneous.

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?

An output schema exists, so return values need not be explained. However, for a highly destructive tool with no annotations, the description is thin on permissions, scope, and reversibility that an agent would need before invoking 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?

Only one parameter ('sql') with 0% schema description coverage, so the description must compensate. It adds some meaning by restricting the param to write statements, but gives no syntax, formatting, or example beyond the three keywords.

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 (execute) and resource (write SQL statement) and enumerates the statement types (INSERT/UPDATE/DELETE). The word 'write' implicitly distinguishes it from the sibling 'query' tool, but it does not name that sibling explicitly.

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 only guidance is 'Use with caution', which is a warning rather than a when-to-use rule. It never says to prefer 'query' for reads or explains which database/scope the statement runs against, so an agent gets no routing logic.

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?

No annotations are provided, so the description carries the full disclosure burden. It does add real behavioral context beyond the schema by stating the time window ('last N days') and, more valuably, the exclusion rule ('Excludes cancelled/failed/refunded orders'). It omits permission needs, rate limits, and confirmation of read-only behavior.

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 tight sentences with zero filler, front-loading the returned metrics before the scoping and exclusion rules. 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?

An output schema exists, so the description correctly avoids explaining return structure. It covers scope, filters, and the key exclusion rule, leaving only the (read-only) safety profile and parameter defaults unstated.

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 0%, so the description must compensate for two undocumented parameters. 'Covers the last N days' maps clearly to 'days', and 'top selling products' loosely implies 'top_n', but it never states that 'top_n' bounds the returned product count or that both have defaults. Partial compensation only.

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 ('Get sales summary') and enumerates what it returns: total revenue, order count, top selling products. This is far more specific than a tautology. It doesn't explicitly differentiate from ambiguous siblings like 'dashboard' or 'get_stock_report', which keeps it short of a 5.

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?

There is no explicit when-to-use guidance, no prerequisites, and no named alternative such as 'dashboard' or 'get_orders'. Usage is only implied by the tool's purpose, so an agent gets no routing help between this and other reporting-style 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Only specified fields are changed' hints at partial-update (PUT/PATCH) semantics but does not state permissions required, whether the change is reversible, whether unknown category_id errors out, or any response behavior. For a mutation tool with zero annotation coverage this is a significant gap.

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

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

Two short sentences with no filler and the partial-update note is front-loaded. Efficient, though underspecified rather than truly concise.

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?

A mutation tool with no annotations, 0% schema coverage on five parameters, and no behavioral detail is incomplete. The existence of an output schema means return values need not be explained, but everything about invocation semantics 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 0% and none of the five parameters are described in text. The description mentions 'fields' generically but does not map them to name/status/meta_title/meta_description, so an agent cannot tell null vs omitted behavior or the meaning of 'status' from the tool definition alone.

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 verb ('update') and resource ('category') and field semantics, but 'category fields' is vague and does not distinguish this from siblings like update_product or update_setting. It gives the gist without naming which fields or what kind of category.

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

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

No when-to-use guidance, no prerequisites, no alternative tools mentioned. The agent is left to infer that this is the tool for editing an existing category rather than creating one.

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?

With no annotations, the description carries the full burden. It usefully discloses partial-update semantics ('Only specified fields are changed') and value encodings (status 1/0, date format), but says nothing about permissions/auth requirements, reversibility, validation failures, or what happens to unspecified fields beyond omission.

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 tight sentences: the action plus the field list first, the partial-update guarantee second. No filler, and the most important constraint 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 an output schema exists, return values need not be explained, and the field-level semantics are well covered for a mutation tool. The remaining gap is behavioral context (auth/permissions, error behavior) for a write operation with no annotations.

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 0%, so the description must compensate, and it largely does: it gives meaning and format for status (1/0), date_end (YYYY-MM-DD), discount, total-use limit (uses_total), and name. It does not explicitly flag coupon_id as the required identifier, leaving one gap.

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 ('Update') and resource ('a coupon') and enumerates exactly which fields can be changed (status, discount, date_end, total-use limit, name). This clearly distinguishes it from create_coupon and get_coupons, though it does not name those siblings explicitly.

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?

Usage is implied: it is for modifying an existing coupon identified by coupon_id, and the phrase 'Only specified fields are changed' hints at a partial-update/PATCH pattern. However, there is no explicit guidance on when to use this versus create_coupon, nor any stated prerequisites or conditions.

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?

With no annotations, the description must carry the full behavioral burden. It notes that find/replace applies to the HTML description field but does not disclose whether all occurrences are replaced, case sensitivity, failure behavior when 'find' is absent, permission requirements, or the destructive nature of the mutation.

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 tightly written sentences with no filler. The core action is front-loaded, followed immediately by the applicable field and the recommended prerequisite.

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 mutation tool with no annotations and 0% schema description coverage, the description is too thin. It omits critical behavioral details such as replace-all versus first-match, error handling, and whether changes are reversible, even though the output schema means return values need not be explained.

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 0%, so the description needs to document all three required parameters. It implicitly maps find and replace through the phrase 'using find/replace', but adds no details about matching behavior, and it never clarifies what information_id refers to or expects.

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 (Update text), resource (information/CMS page), and method (find/replace), and specifies the exact field affected (HTML description). This is enough to distinguish it from sibling tools like update_setting or update_product 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?

It provides one clear prerequisite: 'Use get_information_page first to see current content.' However, it gives no explicit guidance on when to choose this tool over other update_* siblings or when not to use it, so usage is only implied.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that the edit is scoped (only matched text changes, safer than a full rewrite), which is real behavioral context. It does not address what happens on no-match, whether the change is idempotent, required permissions, or reversibility.

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 short sentences, zero filler, with the core purpose leading and the safety rationale and prerequisite following. 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?

An output schema exists, so return-value explanation is not required, and the description adequately covers purpose, mechanism, and prerequisite. For an un-annotated mutation tool with 0% parameter documentation, however, it leaves permission requirements and no-match/error behavior unspecified.

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 0%, so the description must compensate. It clarifies the find/replace semantics well enough to infer the 'find' and 'replace' parameters, but 'module_id' is left unexplained and no format or matching-rule details (case sensitivity, occurrence count) are given.

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 (update text inside a Journal3 module's JSON data) plus the exact mechanism (find/replace). It implicitly distinguishes itself from the J3 settings/ skin-setting siblings by scoping to module JSON, and names its read counterpart get_j3_module. It never explicitly contrasts with update_j3_setting/update_j3_skin_setting, so it stops short of a 5.

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?

Recommends invoking get_j3_module first to inspect current content, which is a genuine workflow prerequisite. It also frames the tool as 'safer than rewriting the entire module'. However, there is no when-not guidance and no explicit routing among the other update_j3_* tools, so usage remains implied rather than stated.

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?

With no annotations, the description carries the full burden of behavioral disclosure but provides virtually none. It doesn't state whether the update requires authentication, what happens if the setting doesn't exist, or whether changes are reversible, leaving the agent with no operational context beyond the basic mutation implied by 'update'.

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, concise sentence that front-loads the essential purpose without unnecessary words. It is appropriately sized for a straightforward update 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?

Given the tool's complexity (mutation, no annotations), the description is insufficient. It omits critical details like permission requirements, error conditions, and how it relates to other setting-update tools. Although an output schema exists (so return values needn't be explained), the behavioral gaps make it incomplete.

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 has 0% description coverage and two required parameters, but they are self-explanatory (setting_name and setting_value). The description adds no syntax, format, or meaning beyond what the parameter names imply, so it neither compensates for the coverage gap nor provides value. Baseline 3 is appropriate for simple, self-describing 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 states a verb (update) and resource (Journal3 theme setting), which is clearer than a tautology. However, it does not differentiate itself from siblings like update_setting, update_j3_skin_setting, or update_j3_module, leaving ambiguity about when to use this tool versus other setting-update 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?

No when-to-use or when-not-to-use guidance is provided. The description does not mention prerequisites, context, or alternatives, offering no help in selecting this tool over its many update_* 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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing beyond the bare verb. It does not say whether the setting must already exist, what permissions are required, whether the change is reversible, whether caching persists, or what side effects occur — critical omissions for a mutation tool.

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

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

A single short, front-loaded sentence with zero waste, but it is under-specified rather than deliberately concise. It earns its words only because there are so few of them.

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?

An output schema exists so return values need not be explained, but for a 3-parameter mutation tool with no annotations and 0% parameter coverage the description is far too thin. Nothing about the Journal3 skin-setting domain, identifier formats, or mutation effects is conveyed.

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 0% and the description adds no parameter meaning at all. The agent is not told what form setting_name takes, whether setting_value must be JSON-encoded, or what skin_id=1 (the default) actually selects.

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 is essentially a restatement of the tool title ('Update J3 Skin Setting' -> 'Update a Journal3 skin setting'), a tautology per the rubric. It does not distinguish this tool from its near-identical siblings update_j3_setting, update_setting, or update_j3_module.

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?

There is no guidance on when to use this tool versus update_j3_setting, update_setting, or the read-side get_j3_skin_settings. No prerequisites, no exclusions, no context of any kind.

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?

With no annotations, the description carries the full burden, and it does disclose two non-obvious behaviors: a history row is always appended, and notify=True only flags the row rather than sending email. However, it omits permissions/auth requirements, error conditions, and whether the change is reversible.

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 short sentences, front-loaded with the primary action and side effect, then the notify caveat, then the lookup hint. Slightly dense with em-dash clauses but nothing wasted.

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?

An output schema exists so return values need no explanation, and the description covers the key mutation side effects for a tool with zero annotation support. It is close to complete, missing only auth/precondition detail for a write operation.

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 0%, so the description must compensate. It explains the counterintuitive notify semantics and implies order_status_id must come from get_order_statuses, but the comment parameter and its default are never mentioned, leaving half the parameters undocumented.

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 ('Change an order's status') and names the exact side effect ('append an order-history entry'), with the admin dropdown analogy making the scope unambiguous. It is clearly separable from siblings like update_product or update_setting.

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 routes the agent to get_order_statuses for status IDs, which is the real prerequisite for this call. It stops short of stating when not to use this tool or what to do if the order is already in that status.

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?

With no annotations, the description carries the full burden. It usefully discloses that only specified fields are mutated, which is essential given every non-required field defaults to null, but says nothing about required permissions, reversibility, invalid product_id handling, or error behavior.

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 short sentences with zero filler, and the partial-update constraint is front-loaded where it matters most.

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 output schema removes the need to explain return values, but for a 7-parameter mutation tool at 0% schema description coverage the definition is thin: no field semantics, no valid status codes, no permissions or failure 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?

Schema description coverage is 0% and the description names no fields. Critically, 'status' is an untyped integer and 'quantity'/'price' have no stated constraints or meaning, so an agent cannot determine valid values from either the description or the schema.

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

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

States a clear verb+resource (update product fields) and names the operation's nature. It does not differentiate from other update_* siblings (update_category, update_setting), but the resource 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?

No indication of when to use this versus the get_product/update_category siblings, no prerequisites, and no hint that a product must already exist. Only the partial-update behavior is implied.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses upsert semantics ('Update or create'), which tells the agent this may write a new mapping. However it stays silent on side effects such as overwriting an existing slug, uniqueness constraints, or required permissions.

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 tight sentences, front-loaded with the action, and each example earns its place by clarifying an otherwise undocumented parameter.

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?

An output schema exists, so return values need no explanation. For a mutation tool with zero annotations, the description should say more about what happens to existing URL mappings, but the core input semantics are adequately covered.

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 0%, so the description must compensate, and it does: 'query' is illustrated with 'product_id=123' or 'category_id=45' and 'keyword' is defined as the URL slug with an example. This gives real meaning to both required parameters, though it doesn't enumerate all accepted query forms.

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 ('Update or create an SEO URL mapping'), and the upsert nature is clear. It does not name the read counterpart get_seo_urls to explicitly separate itself from siblings, but the purpose is unambiguous on its own.

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

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

No guidance on when to use this versus get_seo_urls or when an update is preferred over a create. Usage is only implied by the verb, with no conditions or exclusions stated.

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?

No annotations are provided, so the description carries the full behavioral burden, yet it adds nothing beyond the name. It does not state whether the update replaces or merges values, what permissions are required, whether changes are reversible, or what side effects occur on a mutation.

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 short sentence with no waste and the action front-loaded, but it is under-specified rather than appropriately concise, conveying almost nothing beyond the title.

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 mutation tool with no annotations, no schema descriptions, and no usage guidance, the description is far too thin. The presence of an output schema excuses it from explaining return values, but it still omits the operational context an agent needs 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 0% across three required parameters (group, key, value), and the description supplies no meaning for any of them. The agent cannot tell what a 'group' or 'key' refers to or the expected value format.

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 clear verb (update) and resource (OpenCart setting), so the action is identifiable. However, it does not differentiate from sibling mutation tools such as update_j3_setting, update_product, or update_seo_url, leaving the agent to infer scope from the name alone.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as update_j3_setting or get_settings. The agent must infer usage entirely from the tool name.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the environment (VPS via SFTP), path resolution rules, the side effect of creating parent directories, and the auth requirement (SSH or DDEV). It omits critical write semantics such as overwrite behavior for existing files and permission implications, so it is only partially complete.

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 sentences, each carrying distinct information (action, path rule, side effect, prerequisite) with the core action front-loaded. No filler, though the cautionary sentence is the least 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?

An output schema exists, so return values need not be described. Given a simple two-parameter mutation tool with no annotations, the description covers the environment, auth, path semantics, and a side effect, leaving only overwrite behavior unaddressed. Reasonably complete.

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

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

Schema coverage is 0%, so the description must compensate. It meaningfully clarifies the 'path' parameter ('relative to OpenCart root unless absolute'), which is the non-obvious one. The 'content' parameter is left entirely unexplained, though its meaning is largely self-evident from the tool name.

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 ('Write content to a file') plus the transport mechanism (SFTP) and target environment (VPS), which is more than a tautology. It implicitly distinguishes from the read counterpart get_file. However, it never explicitly names siblings or scope limits beyond the path resolution note, so it falls just short of the top score.

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 a precondition ('Requires SSH or DDEV') and a vague warning ('Use with caution'), which implies when it is applicable. It does not state when to prefer it over alternatives such as update_setting or when a write is unnecessary. Guidance is implied rather than explicit.

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