Shopify SEO Expert: Digital Darts

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

Annotations already declare destructive=true, idempotent=true, openWorld=true and non-read-only, so the safety profile is covered. The description adds genuinely useful behavior beyond that: merchant approval is required, execution is asynchronous and must be followed by get_job_status, and it backfills rather than generates titles. It stops short of saying what happens to any existing title attribute values, which for a destructive tool is a real 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?

Three tightly packed sentences, front-loaded with the action, then prerequisites, then the async follow-up. No filler and no repetition of structured fields beyond a minor restatement of the 50-page cap.

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 annotations cover the safety profile. The workflow (preview -> approval -> apply -> poll) is complete; the only missing piece is what happens to pre-existing title attributes on the links being modified, which matters given destructiveHint=true.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description adds only a pointer that resourceIds comes from preview_link_titles. The batch cap of 50 is repeated from schema maxItems rather than extended. Baseline 3 is appropriate when the schema carries parameter meaning.

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 (fill in) and resource (title attribute on internal links), plus scope (up to 50 pages) and the source of values (each target page's own title). It also identifies itself against the sibling preview_link_titles and the app's Link titles tab, so an agent can distinguish it without opening a 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?

Explicitly names the prerequisite alternative ('Preview with preview_link_titles first') and the approval condition ('get the merchant's go-ahead'), then routes the follow-up to get_job_status. This is a clear when/when-not/next-step chain rather than implied usage.

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?

Adds genuine side-effect and constraint detail beyond the annotations: passing brokenLinkId 'also marks the broken link fixed', and targets must resolve to an existing page or redirects into a 404 are refused. It stops short of stating auth/permission requirements, but the annotations already cover the safety and idempotency profile.

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 tightly written sentences, front-loaded with the core action, then the preferred path, then the constraint. Every sentence carries distinct, decision-relevant 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?

With an output schema handling return values and 100% schema description coverage, the description supplies exactly the missing pieces: the two input strategies, the side effect, and the refusal condition. Nothing an agent needs to call it correctly is 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 100%, so the baseline is 3, but the description adds meaning the schema lacks: brokenLinkId originates from list_broken_links and applies to internal links only, and that it is the preferred input over path. This contextualizes parameter choice, not just 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 specific verb and resource ('Create a Shopify URL redirect') and anchors it to a concrete workflow by naming list_broken_links as the source of brokenLinkId. An agent can distinguish this from siblings like replace_link or flatten_redirect_chain at a glance.

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 ranks two invocation modes ('Preferred: pass brokenLinkId... Or pass path + target directly') and names the prerequisite source tool. It also states the routing/validation condition under which creation is refused, so the agent knows both when and how to call it.

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

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

Goes well past the destructiveHint/openWorldHint annotations by describing the concrete effect of each action — redirect only rewrites internal links to a live page, replace edits content, remove keeps the text or image, dismiss touches nothing on the store. It also discloses a non-obvious operational trait: one job per store at a time, runs in the background, follow it with get_job_status.

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?

Front-loaded with capacity and the action taxonomy, then usage, then the safety/job caveat — a logical order with no filler. It is dense and slightly long-sentenced, but every clause carries decision-relevant 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?

Covers capacity limits, per-action semantics, approval workflow, mutual exclusion, async execution, and the follow-up tool for results, while the output schema and annotations handle return shape and safety hints. Nothing an agent needs to call this correctly is missing.

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

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

The single 'fixes' array parameter is opaque from the schema alone (coverage reported as 0%), and the description supplies the crucial meaning: each entry carries its own action, and target's role differs per action. It stops short of naming brokenLinkId or restating the enum values per entry, relying on the schema for those.

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?

Names a specific verb and resource (fix broken links) and immediately bounds scope: up to 100 per call, with the four action variants defined inline. An agent can distinguish this from create_redirect, replace_link, and list_broken_links without opening any 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?

Explicitly states when to use it (merchant supplies a list of old/new URLs, or a set of links sharing one treatment) and when not to ('for a single link, use create_redirect or replace_link'), naming both alternatives. It also adds a workflow prerequisite: show the merchant what will change and get approval first.

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

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

Annotations declare it is a destructive, idempotent, non-read write; the description goes beyond them by naming two refusal conditions (loops and destinations that would 404), which tells the agent what failures to expect. It does not explain whether intermediate hops are removed or whether permissions are required.

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 concrete before/after example, then the ID source, then the failure modes. 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 no explanation, and the refusal conditions cover the main edge cases for a chain mutation. Minor gaps remain around the fate of intermediate hops and required permissions, but the essential contract 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 coverage is 100% and the single chainId is already documented as 'From list_redirect_chains', so the description's identical statement adds no new semantics. Baseline 3 applies when the schema carries the parameter burden.

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 plus the exact transformation ('turning A → B → C into A → C'), which lets an agent distinguish it from create_redirect and list_redirect_chains at a glance. The arrow notation makes the post-condition unambiguous.

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

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

Explicitly says the chainId comes 'from list_redirect_chains', routing the agent to the discovery tool it must call first. It doesn't contrast against create_redirect for the case where no chain exists, but the precondition is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: the data is a monthly-refresh snapshot (staleness/currency), and the empty-state remediation path via the Backlinks tab.

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 what is returned and followed by the data-freshness caveat. Every clause carries information; nothing is redundant or padded.

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

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

With an output schema present, the description needn't document return values, and it correctly focuses on the operational caveats an agent cannot infer: snapshot staleness and the empty-snapshot precondition. Nothing needed to call or interpret this tool is missing.

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

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

Schema description coverage is 100%, so the single limit parameter (1–25, default 20) and the fact that totals are unaffected by it are already fully documented in the schema. The description's mention of 'top referring domains' loosely maps to this parameter but adds no semantics beyond what the schema states.

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 store's backlink profile snapshot) and enumerates the shape of the payload: total backlinks, referring domains, rank, plus top referring domains. It is clearly distinguishable from siblings like list_broken_links, list_redirect_chains, or get_search_performance, none of which cover backlink data.

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

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

Provides clear operational context — data is only as fresh as the monthly refresh, and if no snapshot exists the merchant must open the Backlinks tab in SEO Expert once. This is actionable guidance for the empty-result case. It stops short of naming when to prefer this over an alternative sibling, but no sibling appears to overlap.

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

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

Annotations already declare the safe-read profile (readOnly, idempotent, non-destructive), so the description's added value is the return-shape disclosure: 'Returns the image itself, downscaled.' That downscaling caveat is real behavioral information an agent cannot get from annotations or the schema, and it matters when judging image quality for alt text. No output schema exists, so it does leave the exact return format (bytes vs. URL vs. base64) unspecified.

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 action and the cardinality constraint, then the usage condition, then the return shape. Nothing is padded or restated.

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 full annotation coverage and no output schema, the description supplies the rationale, the source of the id, and the downscaled-return caveat. The only minor gap is the concrete return format, which matters somewhat for an image-fetching 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 coverage is 100% and the single parameter's schema description already covers the accepted forms (gid, URL, or id from get_resource). The description restates the get_resource provenance but adds no format or syntax detail beyond the schema, so the 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 and resource ('Fetch ONE image') and immediately scopes the input source ('by image id from get_resource'), distinguishing it from the sibling get_resource that produces the id. The emphasis on ONE signals a single-item fetch, not a listing.

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

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

Explicitly instructs when to call it ('Call this before writing alt text') and gives the failure mode that motivates it ('alt text guessed from the product title describes the product rather than the picture'). This effectively routes the agent toward update_image_alt as the downstream step.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds value beyond that: it discloses a one-day cache and the refresh bypass, plus an epistemic caveat that 'not appearing' is a strong signal but not proof of non-indexation. It does not discuss rate limits or data freshness beyond the cache window, so it stops short of the top score.

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?

Front-loads what the tool returns, then the interpretation caveat, then the alternative tool, then the cache behavior. Three compact sentences, none wasted, all additive to 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?

With an output schema present and rich annotations, the description need not explain return shapes. It covers scope, the reliability caveat, the fallback tool, and caching, which is everything an agent needs to call and interpret this correctly.

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

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

Schema description coverage is 100%, so the schema already documents both limit and refresh, including that counts and trend cover every page regardless of limit. The description's 'pass refresh to recompute' largely restates the schema's 'Recompute instead of reading cache'; the one-day cache mention adds a little rationale but not new parameter semantics. 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 and resource: reporting which of the store's pages appear in Google, from Search Console, including counts, the page lists, and the trend. It also explicitly distinguishes itself from inspect_url, so an agent can route between the two 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?

Names the alternative (inspect_url) and the condition that selects it for the definitive per-page check, and clarifies the meaning of 'not appearing' so the agent knows the signal's strength. Refresh behavior is also explained so the agent knows when recomputation is warranted.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds valuable behavioral context beyond that: an audit appears only after a worker picks it up, normally within seconds, which sets expectations for polling. It does not cover edge cases like unknown/expired jobIds or what an empty call returns, so it falls 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?

Three tight sentences, front-loaded with the resource scope, then the calling patterns, then the timing caveat. Every sentence carries information an agent needs.

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 and strong annotations, the description covers nearly everything. The one gap: neither parameter is required, yet the description never says what happens if both are omitted or if both are supplied, which is a real ambiguity for an agent.

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% and the schema already documents the bulk-enum pitfall thoroughly. The description still adds meaning by listing the upstream tools that produce a jobId, which the schema only summarizes as 'From the tool that queued the work.'

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 — progress of background work (SEO audits, link scans, bulk jobs) — and enumerates the job types covered. An agent can immediately tell this apart from siblings like get_indexing_status or run_audit.

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 gives the two calling modes (jobId from run_audit/run_link_scan/apply_link_titles/fix_broken_links, or kind for latest run) and names the alternative behavior it replaces: 'Call this instead of guessing whether queued work has finished.' That is clear when-to-use guidance with named sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered before the description is read. The description adds that both resource-level audit issues and store-level issues are bundled into the result, which is useful behavioral context, but since an output schema exists that information is largely duplicative.

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

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

Two sentences, zero padding, and the operation is front-loaded before the downstream chaining hint. Every clause 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?

Return values are covered by the output schema and the safety profile by annotations, so the description only needs to frame purpose and chaining, which it does. The one unaddressed edge is behavior when the URL matches no resource, which the agent must infer.

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 one parameter at 100% schema description coverage (including a concrete example URL), the schema already carries the baseline. The description adds real meaning by constraining the URL to storefront resource types, telling the agent what kinds of paths will actually match.

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 ('look up') and resource ('storefront URL') and enumerates the accepted resource types (product/collection/page/blog/article), plus what comes back (SEO fields, open audit issues, store-level issues). It does not explicitly distinguish itself from nearby siblings like get_resource or get_seo_summary, so it falls just 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?

Gives clear operative context by naming the follow-up workflow: 'Use the returned resource id with update_meta_tags.' It does not state when this lookup should be chosen over get_resource, inspect_url, or get_seo_summary, and there are no exclusions, so no 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds real value beyond them by disclosing return content and, importantly, the chaining behavior that returned image ids feed update_image_alt.

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 dense sentence with the purpose front-loaded, then the payload and the chaining hint. Zero filler; every clause 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?

With annotations covering safety and an output schema covering return shape, the description only needs to frame purpose, input provenance, and workflow links, all of which it does. The absence of an explicit when-not/alternative keeps it just short of a 5.

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% for the single resourceId parameter, including the gid/numeric/handle resolution rule, so the schema does the heavy lifting. The description restates the id provenance ('from list_resources / get_page_seo') without adding syntax or constraints beyond what the schema provides, matching the baseline 3.

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 ('Full SEO detail for one resource by id') and enumerates the payload (SEO title/description, meta score, image alt text), which distinguishes it from siblings like get_page_seo and get_image. An agent can tell what it returns 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?

Names upstream sources for the id (list_resources / get_page_seo) and a downstream consumer (image ids feed update_image_alt), giving clear workflow placement. It stops short of an explicit when-not or an alternative to use instead, so it is strong context rather than full 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?

Annotations already declare read-only, idempotent, open-world, non-destructive, so the safety profile is covered. The description adds two genuinely new traits: the ~3-day reporting lag (data freshness) and the prerequisite that the merchant has connected Google. No error-path or fallback behavior is described, keeping it at a 4.

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 filler, with the resource identity and panel list front-loaded and the prerequisite/lag caveats trailing. The first sentence is dense with inline parentheticals but every clause carries information the caller needs.

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 needn't be explained; the description covers resource scope, the three modes, data freshness, and the auth prerequisite. The only omission is what happens if Google is not connected (error vs empty result), a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents days, limit, and panel including the fallback-to-28 rule and the ignored-for-overview note. The description largely restates the panel meanings the schema already carries, 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 and resource — Google Search Console performance for the connected property — and enumerates the three panels with what each contains, so an agent knows exactly what it retrieves. It does not explicitly distinguish itself from near siblings like get_seo_summary or get_page_seo, 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?

Gives clear operating context: which panel returns which view, that data lags ~3 days, and that the merchant must have connected Google in the app. It stops short of naming alternatives or stating when-not to use it (e.g. vs get_seo_summary), so no explicit exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description's added content is largely the payload composition (score range, severity buckets), which the output schema already carries, so net new behavioral disclosure is thin.

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, zero filler, with the core subject front-loaded and the entry-point cue placed at the end as a call to action. 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 no-arg, read-only aggregate with a rich output schema, the description covers what the tool is and when to use it; return values need not be re-explained. Only marginal context (how this relates to list_seo_issues or run_audit) is 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?

The tool takes zero parameters, so there are no parameter semantics for the description to clarify; the baseline for a no-param tool applies. Nothing is misleading or missing here.

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

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

States a specific verb+resource ('Overall SEO health of the store') and enumerates the returned content (health score, issue counts by severity, last audit time). It clearly reads as the store-level aggregate rather than a page- or issue-level tool, though it never names the sibling it differs from (get_page_seo, list_seo_issues).

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?

'Start here to understand where the store stands' gives explicit entry-point guidance and clear context for when to reach for this tool first. It stops short of stating exclusions or naming follow-up alternatives, so it is clear but not fully 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?

Annotations already declare readOnly/idempotent/openWorld, and the description adds value beyond them: per-URL live-call latency, the owner-level Search Console access requirement, and the explicit failure mode ('comes back unavailable with an explanation'). That is exactly the behavioral context an agent needs before invoking.

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, zero waste, and front-loaded: the capability comes first, then the cost trade-off, then the access prerequisite. 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?

An output schema exists, so return values need not be explained. Latency, auth requirement, failure behavior, and the sibling alternative are all covered, leaving nothing an agent needs to call this 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?

Only one parameter at 100% schema coverage, so the schema already documents the url field fully ('Full storefront URL on this store'). The description reinforces the single-page scope but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource+scope: 'Definitive index check for ONE page' from Google's URL Inspection API, enumerating the concrete outputs (indexed or not, coverage state, verdict, last crawl, canonical). It is immediately distinguishable from the sibling get_indexing_status, which it names.

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 between alternatives: 'Slower than get_indexing_status because it makes a live call per URL, so use it to confirm a specific page rather than to sweep the store.' Both the when-to-use and when-not-to-use conditions are stated, plus the access prerequisite.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds the useful trait that results are paginated plus the remediation semantics for each link type. It does not state ordering, default page size, or what 'open' means operationally, but the additions are real and go beyond the annotations.

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

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

Four short sentences, front-loaded with what is listed, then remediation routing, then the pagination caveat. Nothing is repeated from the schema and no sentence 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 and annotations cover the safety profile, so the description only needs to orient the agent; it does that plus remediation paths. Minor tension worth noting: the description says external links must be edited in source content, while the linkType schema says external needs replace_link, so the two remediation stories for external links do not match exactly.

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

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

Schema description coverage is 100%, so page/limit/linkType are already fully documented with defaults and clamping behavior. The description mentions brokenLinkId (not a parameter here) but adds no meaning to the three actual parameters, so the baseline 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+resource ('Open broken links') and names the producing subsystem ('the content-graph link scanner'), so the agent knows this is a read of scanner output rather than a scan operation like run_link_scan. It is clearly separable from fix_broken_links, replace_link, and create_redirect.

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 by case: internal links → create_redirect with brokenLinkId, external links → edit source content, many at once → fix_broken_links. That is a full when/when-not/alternative map naming the sibling tools by 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the burden is light. The description still adds useful behavior beyond them: it enumerates what each row contains (path, hops, final destination, loop flag, inbound store links) and notes pagination.

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 definition, then row shape, then remediation and pagination. Every sentence carries distinct information with no restatement of the tool name.

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 annotations covering safety, an output schema covering return values, and full param documentation in the schema, the description supplies exactly the missing context: what a chain is, why it matters, and which tool fixes one.

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

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

Schema description coverage is 100%, so both page and limit are fully documented with defaults and clamping semantics in the schema. The description only restates 'Paginated' and adds no format or usage detail beyond the schema, so the 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 resource with a concrete definitional example (A → B → C) and the consequence it addresses (wasted crawl budget, slow visitors). An agent can immediately tell this apart from list_broken_links or list_seo_issues without opening a 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 clear context for what the rows represent and routes remediation to the sibling tool flatten_redirect_chain. It does not, however, state when to prefer this listing over other audit listings, so there is no explicit exclusion or alternative-selection rule.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: filter conjunction semantics, the default exclusion of drafts/archived/unlisted/unpublished products, and the worst-first ordering. Pagination is mentioned but page size behavior is left to the 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?

Front-loads purpose, then behavior, then ordering — a sensible order with little waste. The parenthetical list of excluded item types is slightly verbose but is the operative detail for the includeUnpublished flag.

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

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

For a read-only list tool with nine fully documented parameters and an output schema, the description covers everything an agent needs to call it correctly: default exclusion behavior, filter combination, and sort order. Return shape is delegated appropriately to the output schema.

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

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

Schema coverage is 100%, so the schema already documents all nine parameters including defaults, ranges, and the 'false is ignored, not inverted' nuance. The description's one addition beyond the schema is the statement that filters combine (AND semantics), which is useful but is the same fact already implied by the includeUnpublished sentence, so it stays at baseline.

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

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

States a specific verb and resource ('List the store's synced content'), enumerates the resource kinds (products, collections, pages, blogs, articles) and the returned fields (SEO fields, meta score 0-100). It does not name or contrast with siblings such as list_seo_issues or get_resource, so an agent must infer the boundary itself.

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 real usage context: filters combine, unpublished items are excluded by default with the rationale that SEO work on them is wasted, and results come back worst-score-first. It never says when to pick this instead of list_seo_issues or get_resource, so the when-to-use 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.

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

Annotations already establish the safe read-only, idempotent profile, so the bar is lower, and the description adds genuine value beyond them: every issue carries a fixUrl deep link into the SEO Expert app, and results are paginated. It stops short of describing ordering guarantees or what happens on an empty result set.

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, no filler, and the core purpose is front-loaded before filters and return-shape details. Every clause carries information the 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?

With an output schema present, return-value detail is not the description's burden, and annotations cover the safety profile; the description supplies the remaining essentials (scope, filters, pagination, fixUrl). Only the absence of sibling routing keeps it from being 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?

Schema coverage is 100%, so page, limit, ruleId, and the severity enum are all fully documented in the schema. The description restates the severity values and the limit ceiling but adds no new meaning such as rule-id format or severity interaction with ordering, so the 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 and resource ('List open SEO audit issues') plus the filter axes, so an agent immediately understands the tool's scope. It does not, however, distinguish itself from adjacent siblings like get_seo_summary, list_broken_links, or run_audit, which also surface audit-related data.

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 word 'open' and the optional severity/ruleId filters imply when the tool is useful, but there is no explicit when-to-use versus get_seo_summary or run_audit, and no stated preconditions (e.g. must an audit have been run first?). Usage is inferable rather than guided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds real value beyond that: it enumerates the returned evidence and discloses the menu-editor limitation that constrains the follow-up replace_link call. It could still say more about cost or scan scope.

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

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

Front-loaded with the core purpose and output, then a short ordering instruction. Slightly dense in the opening clause but every sentence earns its place; 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?

With an output schema present, the description needn't explain return values, yet it still previews them, and it covers sequencing with replace_link and the menu-editor limitation. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single brokenLinkId parameter already documents its source ('From list_broken_links'). The description does not add syntax or format detail beyond the schema, so the 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?

Names a specific verb (preview) and resource (link replacement) and states exactly what the preview returns: the pages, occurrence counts, and navigation menus where the broken link appears. It is clearly distinguishable from replace_link and preview_link_titles.

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 says to run this before replace_link and to show the merchant what would change, and it flags an exclusion (navigation menus belong to Shopify's menu editor and can't be rewritten here). Both the when and the when-not are 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'Read-only' adds nothing. What earns credit is the real behavioral detail: the previewed title is derived from the target page's own title, and omitting resourceIds falls back to pages the audit flagged. It does not explain pagination behavior, but the output schema covers the return shape.

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 with no filler; the scoping and the downstream tool are front-loaded. The fragmentary first sentence reads slightly awkwardly but stays compact.

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

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

For a read-only preview tool with a full output schema and complete parameter coverage, the description supplies what an agent needs: what is previewed, the two selection modes, and the follow-up tool. Pagination and the allowDuplicate toggle are left entirely to structured fields.

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

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

Schema description coverage is 100%, so every parameter is already documented, making 3 the baseline. The description adds only the resourceIds/flagged-pages fallback, which the schema also states, and never mentions page, limit, or allowDuplicate. Value beyond the schema is marginal.

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 names a specific resource (internal links lacking a title attribute) and what is returned (the title the app would fill in). It is clearly distinct from siblings like apply_link_titles or list_broken_links. The opening is a sentence fragment with no verb, which costs a point but does not obscure the purpose.

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

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

It gives two explicit invocation modes: pass resourceIds for specific pages, or omit them to walk audit-flagged pages. It also routes the agent forward by naming apply_link_titles as the write follow-up. It stops short of stating when this tool should be skipped in favor of a sibling, so it is not a full 5.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuine beyond-schema context: this rewrites live store content, requires a preview and merchant approval before acting, and has a hard scope limitation (navigation menus are not rewritable). It stops short of describing reversibility of the edit.

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 tight sentences with zero filler: core action first, then routing versus redirects, then the required preview/approval workflow, then the scope limitation. Each sentence carries distinct decision-relevant 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 no explanation. For a destructive mutation tool the description supplies purpose, alternative routing, prerequisite workflow, approval requirement, and scope limits – everything 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 coverage is 100% with only two parameters, so the schema already documents newHref ('URL or path the link should point at') and brokenLinkId ('From list_broken_links'). The description adds no syntax or format guidance beyond that, so the 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 and resource (edit a broken link's href in store content) and immediately distinguishes itself from create_redirect by declaring this is the fix for an EXTERNAL broken link where 'a redirect can't help there'. An agent can route between replace_link and create_redirect 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 when-to-use (external broken link; internal one when the right page exists), names the alternative that won't work (redirect), specifies the required prerequisite flow (preview_link_replacement first plus merchant go-ahead), and states a when-not constraint (navigation menus can't be rewritten).

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

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

Annotations already declare it is a non-read-only, non-idempotent, open-world write, and the description adds the traits that matter operationally: the audit is asynchronous/background, it is rate-limited to one per day, and it does not return the score itself. These are precisely the behaviors an agent must account for and they are not derivable from the annotations.

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

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

Two sentences, front-loaded with the action and the rate limit, followed by the required follow-up call. Every clause earns its place with no redundant restatement of 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?

An output schema exists, so return values need not be described here; the description instead covers the async nature, the daily cap, and the polling step needed to observe the result. That is everything required to invoke and use this tool 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond confirming it acts on the whole store. No misleading parameter implications are introduced.

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 (Queue/fresh audit) and resource (SEO audit of the whole store), clearly distinct from the read-oriented siblings like get_seo_summary and get_page_seo. An agent knows immediately this is the action that initiates an audit rather than retrieving one.

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 context (whole-store audit), an exclusion/limit (the same one-per-day cap as the in-app button), and routes the agent to the correct follow-up tool (get_seo_summary a few minutes later) since results are not returned inline. Nothing is left to inference.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true and idempotentHint=false, so the agent already knows this is a non-destructive, non-idempotent, outward-reaching operation. The description adds valuable context the annotations do not: the same one-per-day limit as the in-app button, asynchronous background execution, and the required follow-up call to get_job_status.

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, zero filler. The scanning constraint and rate limit are front-loaded, then the sibling relationship, then the async follow-up — a logical order for an agent to 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?

Covers everything the agent needs for a parameterless async job: what it does, when to prefer it, the daily limit, and that a follow-up status call is required. An output schema exists, so return values need no explanation.

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 per the rubric the baseline is 4 with no room for the description to add parameter meaning. Nothing in the schema needs compensating for.

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 ("Scan the store's content for broken links") and immediately contrasts with the sibling list_broken_links by noting that the sibling reports the LAST scan. An agent can distinguish the two 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 an explicit when-to-use condition ("run this first when the merchant has just changed content or asks whether something is still broken") and names the alternative tool it should be preferred over in that situation. Also surfaces the one-per-day rate limit that constrains the decision.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, openWorldHint=true and readOnlyHint=false. The description adds useful context beyond that: what exactly is removed (the seo.hidden metafield), the consequence (indexing/sitemap), and that it is a high-value fix. It stops short of noting reversibility or permission requirements, but the annotation coverage lowers the burden.

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 action and effect, then the detection source, then the safety gate. Each sentence carries weight, though the 'highest-value fixes' phrasing is slightly editorial 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 the description fully covers the action semantics, detection path, and the key prerequisite. For a single-parameter tool this is complete.

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

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

Schema description coverage is 100% and the single resourceId parameter is already documented as coming from list_resources (seoHidden) or get_page_seo. The description restates that list_resources reports seoHidden, adding little beyond the schema, so baseline 3 applies.

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

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

The description names a precise verb (remove the 'hidden from search engines' flag) and the exact mechanism (the seo.hidden metafield) on a single page, plus the downstream effect (indexable, reappears in sitemap). This clearly distinguishes it from its many sibling mutation tools like update_meta_tags or create_redirect.

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

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

It explicitly states the precondition for use – 'Only do this when the merchant confirms the page SHOULD be public' – which is a real when-not rule, and points to list_resources and get_page_seo as the way to detect the hidden state. Nothing about when to invoke it is left implicit.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds real context beyond them: writes to Shopify 'immediately' (live side effect, no staging) and that an empty string clears existing alt text, which is exactly the destructive behavior the hint warns about.

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?

Front-loaded with the operation and scope in the first clause, then immediacy, then quality guidance. Three sentences, each carrying distinct information with no restatement of 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?

With an output schema present and annotations covering the safety profile, the description only needs to add the non-obvious operational facts, which it does: single-image scope, immediate write, and clearing semantics. Nothing needed to invoke it correctly is missing.

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

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 meaning the schema does not: the schema allows maxLength 512 and states 125 characters as an upper bound for good alt text, while imageId is tied back to get_resource. That constrains usage beyond the raw type declaration.

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 ('Set the alt text for ONE image') and pins the scope to a single image by id, which cleanly separates it from the sibling update_image_alt_bulk. An agent can pick this over the bulk variant without inspecting 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 clear when-to-use context: operating on one image by imageId sourced from get_resource/get_image, and notes that an empty string clears the value. It implies but never explicitly names update_image_alt_bulk as the alternative for multi-image work, so there is no stated exclusion.

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

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

Annotations only carry the safety flags (destructive, idempotent, openWorld); the description adds what those flags actually mean in practice: writes land in Shopify immediately, items succeed or fail independently, and failures are reported per id. It also discloses that an empty string clears the alt, which is the destructive path an agent needs to know about.

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?

Front-loaded with the batch limit and write behavior, and every sentence carries information. The 'Same rules as update_image_alt' clause then restates the 125-character/clearing rules that already appear in the schema, which is mild 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?

For a 1-parameter bulk mutation with an output schema present, the description covers everything an agent needs: id provenance, the mandatory get_image step, partial-failure semantics, and authoring rules. Return values need not be explained since the output schema exists.

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% and both nested fields are documented there, so the baseline is 3. The description adds a real constraint beyond the schema: the 125-character authoring rule (stricter than the schema's maxLength of 512) plus content rules (no 'image of', no keyword stuffing). That the two limits disagree is worth resolving, but the added semantics are genuine.

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 (Set), resource (alt text), batch scope (up to 50 images in one call), and the id source. The reference to update_image_alt makes the single-vs-bulk split inferable, so an agent can separate it from its closest sibling 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 concrete prerequisites: image ids come from get_resource, and the agent must call get_image BEFORE writing each alt, with a reason (alt guessed from a product title describes the product, not the picture). It stops short of an explicit 'use update_image_alt for a single image' routing statement, but the when-to-use context is clear.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds real context beyond that: writes hit Shopify immediately, empty string clears a field, and hand-edited fields are locked against templates and marked manual. This is valuable behavioral detail, though write-reversibility is not addressed.

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 and scope are front-loaded, then immediate-write behavior, guidance, and clearing are packed efficiently. Dense but every sentence carries information; the guidance clause could arguably be split but it is not 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. The description covers scope, ID source, write immediacy, clearing, character guidance, and lock/manual-edit behavior, leaving nothing essential for a correct call missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by giving recommended length guidance (≤60 chars titles, 120-160 descriptions) that differs from the schema's hard maxLength limits of 70/320, and by confirming the empty-string clearing semantics.

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 (set SEO title and/or meta description) and scopes it explicitly to ONE resource by resourceId. The 'ONE resource' framing distinguishes it from the sibling update_meta_tags_bulk without either schema being opened.

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?

Tells the agent where resourceId comes from (list_resources / get_page_seo) and implies single-resource scope, giving clear context for when to use it. It stops short of explicitly routing to update_meta_tags_bulk for multi-resource updates, so no true exclusion is 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?

Goes well beyond the annotations: 'Writes to Shopify immediately' clarifies timing, and 'items succeed or fail independently and failures are reported per id' discloses partial-failure semantics the destructive/idempotent hints cannot convey. This is exactly the kind of operational detail an agent needs before calling a mutating bulk 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?

Front-loads the action and the cap in the first clause, then layers rules and caveats. It is a dense paragraph but each sentence carries distinct information; only the personal-voice aside about uniqueness is slightly informal for the volume of rules packed in.

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

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

With an output schema present the description need not explain return values, and it correctly focuses on write timing, per-item failure handling, and constraints. It is essentially complete for a bulk mutation tool; adding the single-vs-bulk routing would close the remaining gap.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description adds real meaning: the 50-item cap, 'empty string clears' semantics, and editorial constraints (front-load the keyword, no stuffing). It also surfaces a numeric limit (titles ≤ 60, descriptions 120-160) that is stricter than the schema's maxLength of 70/320, giving the agent usable guidance rather than just hard caps.

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 (Set), the resource written (SEO titles and/or meta descriptions), and the batch scope ('up to 50 resources in one call'). It also names its single-item sibling ('Same rules as update_meta_tags'), so an agent can distinguish it from update_meta_tags and update_image_alt_bulk without opening a 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 clear context: resource ids come from list_resources, and behavior mirrors update_meta_tags. It adds a use-caveat ('Write UNIQUE copy per page, because reusing one title across items defeats the point') but never explicitly says when to prefer the single-item update_meta_tags over this bulk variant.

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