shopify_update_metafield

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

Annotations already carry readOnlyHint=false, destructiveHint=true, and idempotentHint=true, and the description's 'Create or update' matches those hints rather than contradicting them. It adds some behavioral context not in the annotations, such as upsert semantics and that approval_ref is 'Approved platform task UUID when resuming a write', but it does not explain what gets overwritten, ownership of effects, or any side-effect caveats.

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 purpose is front-loaded in one clear sentence, followed by a compact Args list where every line adds parameter information. There is no filler, repetition, or disorganized prose.

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 description is functionally adequate for a 12-parameter write tool that has an output schema, but the cross-cutting fields (effect, idempotency_key, approval_ref, project_ref) are only glossed. An agent still lacks enough context to know when approval_ref is needed, what values effect can take, or how the platform's write-approval flow works; the missing usage guidance further reduces 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?

With 0% schema description coverage and no enums in the schema, the prose carries the full burden and mostly succeeds: it marks owner_id/namespace/key/value as required, lists valid owner_type values, gives type examples, and states defaults for owner_type and type. A few entries are thin ('Exact project correlation reference' is almost tautological, 'effect' is cryptically defined), and the schema's all-optional/default-null properties conflict slightly with the description's 'required' labels.

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 opening line names a concrete verb+resource ('Create or update a metafield on a Shopify resource') and the Args list narrows the target to PRODUCT/CUSTOMER/ORDER/VARIANT/COLLECTION. It is clear, but unlike the high-watermark examples it never explicitly contrasts itself with shopify_get_metafields or other sibling metafield tools, so an agent gets no explicit sibling differentiation.

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 statement of when to use this tool or when to prefer an alternative; the description only lists Args. The 'Create or update' phrasing implies upsert usage, but no exclusions or references to shopify_get_metafields/list_metafield_definitions are given, so the agent must infer selection context.

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