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

With no annotations, the description carries the full disclosure burden. Beyond implying read-only via 'Read', it says nothing about permissions or scope needed, what happens when no custom CSS is configured, or what the response looks like — and it hardcodes a store ID (123456789), which is ambiguous if the agent operates on other stores.

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 hardcoded store number is the only questionable element, as it may be static context rather than an argument to 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?

For a zero-required-parameter read tool this is close, but with no output schema and no annotations the description should say at least what the return value is (raw CSS text? empty when unset?) and whether version_id selects a historical version. Those gaps matter for correct invocation.

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

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

Schema description coverage is 100% and the single optional version_id parameter is documented there, including its default (987654321) and the sibling tool to source it from. The description adds no parameter meaning beyond that, so baseline 3 applies.

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

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

States a specific verb (Read) and resource (the store's custom CSS) and even names the UI location it corresponds to. It competes clearly with custom_css_update and custom_js_get, though it never explicitly contrasts itself with those siblings.

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 or when-not guidance, no mention of the read/write pairing with custom_css_update, and no note about which store/version context applies. The intended usage is only inferable from the verb 'Read'.

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 delivers: it discloses that changes go live on the published version immediately, that the whole stylesheet is overwritten, and that a local backup is taken beforehand. It omits auth/permission requirements and how/where the backup can be restored, which keeps it just short of a 5.

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?

Five short sentences, each carrying a distinct operational fact, with the core action front-loaded and the safety steps following. No repetition or filler.

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

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

For a destructive two-parameter mutation with no output schema, the description covers liveness, full-overwrite semantics, backup, and required merchant confirmation. It leaves version_id semantics and permission requirements implicit, but nothing essential for a correct call is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real value by stressing that css must be the complete stylesheet and not a fragment. version_id is left entirely to the schema, so it stops short of full coverage.

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

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

States a specific verb and resource ('Replace the store's entire custom CSS') and makes the replacement semantics explicit versus a fragment edit. The read-before-write instruction implicitly distinguishes it from custom_css_get, so an agent can tell the full-overwrite tool apart from the read tool without opening either 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?

Gives explicit procedural preconditions: 'Always read the current CSS first', 'pass the full new stylesheet (not a fragment)', and 'get their OK before calling'. These are concrete when/how conditions that route the agent correctly and name the read sibling implicitly.

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 behavioral disclosure. It does add one genuinely useful fact beyond the schema: the enabled status is NOT returned here but lives in theme_versions_list. It does not mention permissions, behavior when no custom JS exists, or what the returned content looks like.

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, front-loaded with the action and resource, followed by the one genuinely non-obvious fact. The hardcoded store ID is wasted, misleading specificity rather than 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 single-parameter read tool with no output schema, the description covers the essential split: JS content comes from here, enabled state comes from theme_versions_list. Missing only edge-case behavior (no JS configured, invalid version_id) and any hint about return shape.

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

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

Schema description coverage is 100% and the single version_id parameter is already documented with its source and default, so the schema does the heavy lifting. The description adds nothing about version_id and instead hardcodes store 123456789, which risks confusing the agent about what is actually parameterized.

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: 'Read the store's custom JavaScript'. This clearly separates it from custom_js_update and custom_js_toggle by action type, but it never names those siblings or scopes the read (whole store vs a specific theme version), despite the tool taking a version_id.

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

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

Usage is implied rather than stated — a 'read' verb signals inspection, and the second sentence usefully tells the agent to consult theme_versions_list for the enabled state. There is no explicit when-to-use/when-not or routing to custom_js_update/toggle.

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 is a state-changing operation that preserves the script content and that merchant consent is required. It says nothing about which theme/version is affected when omitted, whether the change is instantly live, or what the result looks like, so a mutation tool remains under-described.

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 filler, with the action stated before the approval caveat. 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?

For a two-parameter toggle with no output schema, the description covers action, scope, and consent. It omits what the tool returns and which theme version is targeted by default, but the schema already documents the version default, so little is missing.

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

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

Schema coverage is 50%: version_id is documented in the schema with its default, while `enabled` relies on its type alone. The description's 'on or off' loosely maps to `enabled` but adds no format, default, or edge-case guidance for either parameter. Baseline 3 for partial coverage is appropriate.

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

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

States a specific verb ('turn on or off') and resource ('the store's custom JavaScript') with a scope qualifier 'without changing the code' that separates it from custom_js_update. An agent can tell this is an enablement toggle, not a content edit, 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?

'Without changing the code' implicitly routes the agent here rather than to custom_js_update when only the enabled state should change, and 'Get the merchant's OK first' supplies a real prerequisite. No sibling is named explicitly and no when-not-to-use case is given, so it falls short of 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?

With no annotations, the description carries the full burden and does real work: it discloses that the script executes on every storefront page once saved, that the previous JS is backed up locally, and that merchant confirmation is required. Remaining gaps are permissions scopes and failure behavior, but this is well above the bar for an unannotated 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?

Four short sentences, each carrying distinct information (what it does, runtime effect, workflow prerequisite, confirmation gate) with the destructive nature 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?

Covers the mutation, its blast radius, the backup, and the approval gate, which is what an agent needs before calling a destructive write. It stops short of describing what a failed save leaves behind or the return shape, but no output schema exists and the critical risks are stated.

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

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

Schema coverage is 100%, so baseline is 3; the description adds genuine meaning by clarifying that js must be the complete script, not a fragment or patch. version_id is left entirely to the schema, which is acceptable given its own 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 specific verb and resource ("Replace the store's entire custom JavaScript") plus the key scope fact that it overwrites everything rather than patching. That framing alone distinguishes it from the read-only custom_js_get sibling and from custom_js_toggle.

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?

"Always read the current JS first and pass the full new script" and "Show the merchant the change and get their OK before calling" give explicit prerequisites and ordering. It doesn't name custom_js_toggle as a lighter-weight alternative for enable/disable, so the sibling routing is only partly covered.

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