Ask AI

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

With no annotations provided, the description carries the full burden and does so: it discloses that it does NOT capture live from source, that a measured verdict is REFUSED when no tracked metric has a post snapshot, and what force:true or verdict:'abandoned' do instead. It also states the side effect (status='closed'). This is unusually rich behavioral disclosure.

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?

Dense but front-loaded: trigger first, then behavior, then failure modes and remedies. The refusal/retry path repeats itself somewhat ('record snapshots then retry' appears twice conceptually), costing a little crispness, but nearly 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?

For a mutation tool with no annotations and no output schema, the description covers trigger, prerequisites, refusal behavior, overrides, and the resulting state change. An agent has everything needed to invoke it correctly or route to the prerequisite 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%, so the baseline is 3 and the schema already documents force, notes, verdict and interventionId. The description still adds selection meaning by explaining when force is required and contrasting measured verdicts against 'abandoned', which helps an agent choose values rather than just read types.

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 (complete/close) plus resource (an applied intervention) and enumerates exactly what it computes: attaches the latest recorded post-fix snapshot, computes deltas vs baseline, flags expected-delta outcomes, and sets verdict plus status='closed'. It is clearly distinguishable from the read-only get_interventions sibling.

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

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

Opens with an explicit TRIGGER ('call WITHOUT asking once an applied intervention's check date has passed') and routes the agent to get_interventions(dueForCheckIn: true) for candidate discovery. It also names the prerequisites (record_metric_snapshot) and the escape hatches (force:true, verdict:'abandoned'), covering when-not and alternatives.

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

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

With no annotations, the description carries full behavioral disclosure and does so excellently: it warns that completed purchases never enter the dataset, instructs not to derive abandonment rates or compare to order totals, and enumerates five fields that will always be null with an explanation of why. This is exactly the kind of context an agent needs to avoid misinterpretation.

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

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

The description is dense but front-loads the purpose, then the report contents, then the critical universe limitation and null fields. It's a bit long due to the exhaustive metric list and null-field enumeration, but every sentence serves a purpose and there is no filler.

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

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

For a complex analytics tool with no annotations and no output schema, the description covers the purpose, data contents, caveats, and explicit limitations. An agent has everything needed to call and interpret the 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?

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds no parameter-level detail beyond what the schema provides; the baseline of 3 applies when the schema does the heavy lifting.

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

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

The description clearly states it returns cart abandonment analytics and enumerates the two report types (stats, top_products) with the specific metrics each contains. It distinguishes itself from siblings like get_top_products or get_orders by explicitly scoping to abandoned-checkout records, though it doesn't name competing tools directly.

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

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

The description explains the data universe (only abandoned checkouts) and lists what's never available, but does not say when to use this tool versus e.g. get_top_products or get_orders, nor does it state prerequisites. Usage is implied through the report enum but not 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?

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses the detection method and thresholds, the ranked output fields, the mutually exclusive drivers/driverSummary vs driversNote semantics (with the interpretation that driversNote means a sitewide, non-channel cause), and the required follow-up call pattern. This is far beyond what a bare 'detect anomalies' line would convey.

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 before method and edge-case warnings, and the dense driver/investigate paragraph is high-value rather than filler. It is long, but nearly every clause (thresholds, driversNote semantics, verbatim-window warning) prevents a real invocation mistake.

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 no output schema and no annotations, the description compensates fully: it enumerates returned fields, explains the two attribution shapes, and describes the investigate handoff including why the target's default window fails. An agent has everything needed to call it and act on results.

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

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

Schema description coverage is 100% and both parameters are self-documented, so the baseline is 3. The description only alludes to the baseline window ('prior 4 weeks'), which mirrors the lookbackWeeks default, and says nothing about _offset pagination beyond what the schema already 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+resource ('Anomaly detection across revenue, conversion rate, and refund rate') with explicit scope ('for each of your stores, works for a single store too'). The methodology sentence (7-day vs prior 4 weeks, +/- 1.5 SD or 25%) and return contents make it unmistakable versus siblings like get_weekly_trends or get_daily_metrics.

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 positions the tool as a session opener ('anything weird happening?') and warns that the target tool's default 30-day window will not surface a one-week move, instructing the agent to use `investigate` verbatim. It does not, however, name a competing tool to use instead when the agent wants trend confirmation rather than anomaly scanning.

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

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

No annotations, so the description carries the burden and does well: it discloses cost ('cheap'), internal debouncing, safety ('safe to call first'), and the subtle expected output shape including a VERBATIM next-call instruction for 'investigate'. It doesn't detail pagination (left to schema) or rate limits, but the behavioral profile is otherwise rich.

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 imperative 'START HERE... call it FIRST' then enumerates the returned content compactly, closing with when-to-use triggers. Dense but every clause earns its place for a session-opening composite 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 no-required-param, no-output-schema orientation tool, the description is complete: it explains what is returned, how to lead the first response (brokenConnections, whatChanged, _tip_actions), and the silent/verbatim invocation behavior. 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% and both parameters ('_offset', 'sinceDays') are documented in the schema, so baseline is 3. The description adds useful context by explaining sinceDays defaults to 7 / max 90 and that it feeds the 'what changed' digest, and notes the rolling-window caveat, but this overlaps what the schema already 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 ('one call that orients you') and enumerates exactly what it surfaces: stores/currencies, brokenConnections, open fix-work, focus-plan headline, store identities, top anomalies, and a what-changed digest. It distinguishes itself from siblings like get_anomalies or get_interventions by being the composite orientation call, and even names sub-fields like 'driverSummary' and 'investigate' that no sibling would return together.

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?

Explicit when-to-use ('START HERE at the beginning of a session — call it FIRST') and even specifies behavioral constraints ('SILENTLY', don't announce or narrate), plus the trigger questions ('how are things?' / 'what should I look at?'). This is a model of routing guidance.

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

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

With no annotations, the description carries full burden and delivers: it enumerates the exact return contents (campaign metadata, Klaviyo attribution claim, Shopify orders/revenue/new-customers, baseline counterfactual, lift, attributionAnalysis), discloses the baseline methodology and its rationale, and explains the disambiguation behavior when campaignName matches multiple records.

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 purpose and methodology, then examples, then the PREFER statement, then parameter guidance — logical ordering. It is dense and long, but most sentences earn their place; the opening rhetorical question is a minor stylistic indulgence.

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 complex no-annotation, no-output-schema synthesis tool, the description covers purpose, methodology, return shape, behavioral edge cases (disambiguation), alternative routing, and parameter tuning — everything an agent needs to call it correctly and interpret the result.

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 already 100%, but the description adds genuine value beyond it: it explains the campaignId vs campaignName trade-off (exact vs fuzzy, returns most recent match plus disambiguation block), and justifies the 7-day default with the contrast against Klaviyo's 5-day attribution window and the high-AOV extension case.

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 ('measures the real impact of a specific Klaviyo campaign') and explicitly names the methodology (day-of-week-aligned baseline, post-send window vs same N days one week earlier). Clearly distinguished from siblings like get_marketing_performance and get_store_summary by its cross-source synthesis framing.

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 concrete example queries ('did the SUMMER20 campaign work?', 'is my abandoned-cart flow driving revenue?') and an explicit PREFER-over instruction naming the alternative workflow (get_connector_data + get_store_summary) and why not to use it. Also gives tuning guidance for windowDays.

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

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

With no annotations, the description carries the burden and does well: it discloses ranking by lift, lift interpretation bands, the per-pair metrics returned, and the suppression rule for low co-occurrence counts with the rationale (lift instability on small samples). It omits auth/permission or rate-limit context, but the behavioral disclosures are substantive.

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 then the two report modes; dense but every clause carries information an agent needs. Slightly long but no filler sentences.

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?

No output schema exists, yet the description enumerates the returned fields (support, confidence, lift, verdict, avgDaysToCoBuy) and their interpretation, filling the gap. Combined with 100% schema coverage for inputs, it is complete 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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining how to read lift values (>3 strong, <1.5 weak) and why minCoOccurrences matters, which enriches the agent's interpretation of those parameters.

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

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

States a specific analysis (co-purchase/market-basket), the required input (productTitle anchor), and the output (other products ranked by lift). It clearly separates the two report modes so an agent can distinguish basket vs lifetime without ambiguity.

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

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

Gives explicit when-to-use guidance per report mode: basket for bundles, 'frequently bought together' widgets, and post-checkout upsells; lifetime for email flows and longer-horizon recommendations. It does not name a sibling alternative or state exclusions, but the contextual routing is strong.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return contents of both reports (product counts, pricing, inventory, SEO, optional sales data) and clarifies the SEO field mapping to Shopify metafields. It does not state the read-only/safety profile, auth needs, or rate behavior, leaving those gaps.

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, then the report breakdown, then the SEO mapping, then usage examples. Dense but every sentence carries information; nothing is redundant.

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

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

A 7-parameter, dual-report tool with no output schema is well covered: both report modes, SEO semantics, and usage triggers are documented. Minor gaps remain around pagination behavior (only in schema) and permissions, so not quite exhaustive.

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 real meaning by explaining what each report enum value returns and by clarifying that seoTitle/seoDescription map to Shopify's global.title_tag/global.description_tag. It also implies which parameters apply to the products report (sales data dates, collectionId/collectionTitle), adding cross-parameter context beyond the schema.

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

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

States a specific verb (Get) and resource (product collections and their contents), then enumerates the two report modes so the agent knows exactly what the tool returns. It is distinguishable from catalog-oriented siblings like get_product_catalog and get_top_products because it centers on collections and their membership.

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 triggering queries ('how many products in the sandals collection?', 'what products are in collection X?') and ties each to the relevant report type, which effectively tells the agent when to pick list vs products. It stops short of naming an explicit alternative sibling or a when-not-to-use case, so it is clear context rather than full routing guidance.

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

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

With no annotations, the description carries the full burden and does most of it: it discloses that only connected sources appear, and that in multi-store mode the store param filters only Shopify data while GA4/Klaviyo/Search Console/Gorgias stay account-level and always aggregated. It does not cover auth requirements, rate limits, or the concrete return shape beyond 'lean snapshot'.

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 capability, then the drill-down guidance, then the multi-store caveats. Dense and mostly waste-free, though the final multi-store/store-comparison sentences are long enough that some tightening is possible.

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?

No output schema and no annotations, so the description must supply context, and it does: scope, trigger scenarios, cross-source aggregation behavior, and store-filtering limits. What is missing is return-shape detail (what fields a snapshot contains, pagination interaction with _offset).

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 startDate/endDate/_offset semantics are already documented, making 3 the baseline. The description adds useful behavioral detail about the store param's partial filtering, but that parameter does not appear in the input schema, so the added semantics do not map cleanly onto any documented parameter.

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

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

States a specific verb+resource ('Get a unified dashboard') and enumerates the metric domains covered (revenue, traffic, marketing, email, organic search, UX, support, reviews, subscriptions, loyalty), which clearly separates it from the many single-domain siblings like get_marketing_performance or get_product_analytics.

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 trigger phrases ('Give me an overview', 'How is the business doing?') and routes the agent onward ('then drill into specifics with individual tools'). It also names the alternative for a related need, get_store_comparison, and notes the condition under which that tool exists.

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

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

No annotations are provided, so the description carries the full burden and does so richly: per-store scoping in multi-store mode, null (not fake-low) for unmatured cohort milestones, churned customers excluded beyond maxDaysInactive, likelyWholesale flagging, exclusion of names/emails by design, and the warning that the mean is misleading when lifetimeValueDistributionNote is present.

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, but the report catalogue is delivered as one enormous run-on sentence that is hard to parse. The content is dense and largely earns its place, but the structure undermines quick scanning.

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 10-parameter tool with no output schema, the description does a good job describing what each report returns (AOV splits, repeat rate, retention % and LTV at 1/3/6/12 months, adminUrl and tags on lapsed rows). The missing piece is the unexplained store parameter referenced in prose but absent from the schema.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including defaults, so the baseline is 3. The description mostly restates schema-level facts (store scoping, defaults) and notably references a 'store param' that does not appear in the input schema, which limits the added value.

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

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

States a specific verb+resource ('Get customer behavior and retention insights') and then enumerates all eight report values with the metric each returns, letting an agent distinguish it from get_customers, get_insights, and get_metrics_comparison without opening schemas.

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

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

Provides strong per-report usage context ('LEAD WITH MEDIAN when describing the typical customer', 'raise to see the long tail', win-back targeting exclusions). It does not explicitly say when to prefer this tool over sibling tools like get_customers, so it falls short of a full when/alternatives statement.

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 largely succeeds: it discloses the country-derivation limitation (shipping address, not customer records, and Shopify access constraints), tag_segments defaults (non-purchaser cohort, minTagVolume 200), and the cross-report data flow needed to call customer_history. It does not mention pagination behavior or response shape, which is a minor omission for a read-only analytics 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-loaded with purpose, then structured report-by-report with parenthetical detail. It is long and dense, and the tag_segments entry is notably verbose, but the length is largely justified by five distinct report modes and ten parameters. Some trimming of repeated cohort/default phrasing would tighten it.

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?

No output schema and no annotations, so the description must carry behavior, and it does: report selection, defaults, limitations, alternatives, and data-flow prerequisites are all present. Residual gaps are pagination (only in schema) and result-format expectations, both modest for an analytics reader.

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 real value the flat schema cannot: it maps each parameter to its report (rank, tag, customerId, sortBy, tags, purchaserFilter, minTagVolume) and explains cross-report provenance (use customerId from the 'top' report; rank=1 for top customer; tags cross-tabulates). This report-to-parameter routing is beyond what the schema conveys.

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

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

States a specific verb+resource ('Get customer analytics by dimension') and then enumerates all five report modes with their distinct outputs (segments, top, by_country, customer_history, tag_segments). It explicitly rules out a nearby capability ('This tool does NOT support product-level filtering'), so an agent can differentiate it from siblings like get_orders and get_customer_insights.

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 explicit when-to-use guidance per report, including 'BEST FOR' phrasing for tag_segments, default behaviors, and a named alternative: use get_orders(report: 'by_product') for 'how many customers bought product X?'. That is a textbook when/when-not/alternative disclosure.

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 so well: it discloses that the operational domain reads a pre-computed DailyStat rollup ('updated by the scheduler, not a live query'), that P&L fee coverage can be partial and the response states it, and that money values are formatted currency strings. It stops short of describing auth requirements or rate limits, so it is strong rather than exhaustive.

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?

Well front-loaded: the cross-domain warning about 'daily' comes before the per-domain bullets, so an agent gets the critical constraint first. The three bullets are logically structured, but the repeated 'requires Shopify Plus/Advanced' and default-window restatements across bullets add avoidable redundancy for a description this long.

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?

No output schema exists, so the description compensates by enumerating the returned fields per report (revenue, sessions, cvr, aov, newCustomers, fulfillmentRate, etc.) and output shape ({ period, data, charts, presentation }). For a 6-parameter, three-domain dispatcher, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description supplies meaning the schema explicitly defers to it: the valid `report` values per domain (the schema's `report` field has no enum and says 'see tool description'), which report is the default in each domain, and the fact that funnel has no real default window. That is real added semantic value beyond the schema.

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

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

States a specific verb and resource (get daily/period numbers) and immediately qualifies it with the three-domain dispatch model, going as far as warning that the same `report:"daily"` value yields a DIFFERENT payload per domain. This is precisely the kind of disambiguation an agent needs to separate it from siblings like get_store_summary or get_weekly_trends.

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 routing rules ('Use "funnel" for sessions/CVR/traffic questions, "revenue" for channel/country/P&L breakdowns, "operational" for dashboard KPI tracking'), plus per-report prerequisites (Shopify Plus/Advanced, traffic sync) and default-window behavior per domain. It also warns when not to assume — never assume 'daily' behaves the same across domains.

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

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

No annotations, so the description carries the full behavioral burden and does so well: it discloses what is returned (connection status and record counts), that Shopify is always connected, and that non-connected sources yield empty results. No contradiction with 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?

Front-loads the imperative 'CALL THIS FIRST', then details what is returned, then gives the usage rationale. Every sentence earns its place with no redundancy, and the structure flows logically.

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

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

Given the tool's role as a discovery/capabilities endpoint, the description is complete: it lists all expected sources, explains the meaning of 'not_connected', and states the impact on subsequent queries. No output schema exists, but the description sufficiently conveys return content.

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 (_offset) with 100% schema description coverage that fully explains pagination behavior, including the trigger condition (_pagination.hasMore). The description appropriately omits parameter details since the schema is self-sufficient.

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+resource (get data sources) and enumerates the exact sources returned (Shopify, Triple Whale, Klaviyo, etc.). Distinguishes itself from all 50+ siblings by being the only sources/capabilities-listing tool.

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

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

Explicitly states 'CALL THIS FIRST' and 'Use this to understand what data is available before making other queries', providing a clear when-to-use directive. It also gives the consequence of ignoring it: tools for non-connected sources return empty results.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses little: no statement of read-only vs mutating, no auth/permission requirements, no rate limits or cost notes. Pagination behavior exists only in the schema's _offset field, not in the description. The report-content summaries describe outputs rather than behavior.

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

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

A single tightly-packed paragraph with the core purpose front-loaded and the four report modes as a scannable list. No filler sentences, though the dense em-dash nesting trades some readability for compactness.

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 7 parameters, no output schema, and no annotations, the description sensibly fills the output gap by summarizing what each report returns. It stops short of stating whether startDate/endDate apply to all four reports or only some, which is the main residual ambiguity for a multi-mode analytics tool.

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

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

Schema description coverage is 100%, so every parameter (code, limit, report, sortBy, startDate, endDate, _offset) is already documented in structured form, making 3 the baseline. The description adds marginal routing value by tying 'code' and 'limit' to specific report types, but nothing the schema does not already convey.

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 discount code analytics') and then enumerates the four report modes, so an agent knows exactly what surface the tool covers. This enumeration also distinguishes it from adjacent analytics siblings like get_campaign_impact or get_marketing_performance, which do not expose per-code breakdowns.

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 useful intra-tool routing ('code_details requires code param', 'by_product optionally filter by code'), which tells the agent how to drive each report. However, with ~55 siblings including several overlapping analytics tools, there is no explicit when-to-use-this-vs-alternative guidance or exclusion criteria, so cross-tool selection 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?

With no annotations, the description carries the full behavioral burden and does so richly: the plan does NOT auto-expire, re-asks return the same plan with LIVE item state, and it explains what 'done' means per item type ('tackle' vs 'check'). It also discloses the fallback synthesis bundle contents and the embedded _instruction directing a save_focus call — far beyond a name restatement.

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 session-opener guidance are front-loaded, and each sentence adds substance about lifecycle or fallback. It is dense and somewhat sprawling with nested parentheticals, which slightly hurts scannability, but there is little wasted content.

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?

There is no output schema, so the description must explain returns — and it does: the current plan with LIVE item states, or a synthesis bundle enumerating open findings, due interventions, outcomes summary, trends, and carried-forward items. Combined with the lifecycle and refresh semantics, an agent has everything needed 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 top, _offset, and refresh. The description reinforces refresh with the 'plan my week' idiom and packetizes its effect, adding marginal meaning. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

States a specific verb and resource — returning the merchant's current weekly plan, framed as the committed 'what to work on now' list. It clearly differentiates itself from the write-side siblings (save_focus, update_focus_item) by describing both the read of the existing plan and the synthesis fallback. An agent can identify this as the read-oriented session opener without ambiguity.

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

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

Explicitly frames usage ('Use as a session opener') and gives the trigger for the alternative path ('refresh: true' / 'plan my week'). It implies when the fallback synthesis fires (no plan exists or refresh requested). No explicit when-not guidance, but the conditions are clear enough to route correctly.

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 so richly: it names the four methods, mandates leading with range and confidence over the point estimate, describes graceful degradation to low confidence when history is thin, and warns that per-store values are never summed across currencies. This is substantial behavioral disclosure beyond 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-loaded with purpose and driver questions, then organized into return-shape and honesty sections. Effective structure, though it is dense and long; a few clauses (e.g. the full output field enumeration) could be trimmed given the schema already exists.

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 forecast tool with no output schema, it describes the return shape well (stores array, currentMonth, horizon, method, confidence, assumptions, charts) and sets expectations about honesty and degradation. Minor gaps remain on exact band semantics and pagination behavior, but the core 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%, so all four parameters are already documented in the schema. The description reinforces defaults (metric defaults to revenue, horizon defaults to 1) and reinforces the per-currency store behavior, but adds little syntax or format beyond what the schema provides. Baseline 3 is appropriate.

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

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

States the verb (forecast) and resource (a metric) and immediately frames the questions it answers ('what should I expect?', 'are we on track this month?', 'project next month'). This distinguishes it from descriptive siblings like get_daily_metrics and get_yoy_monthly, which report history rather than project forward.

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 when to reach for it via the quoted user questions and notes that current-month projection works immediately while forward months need snapshot history. It does not explicitly name which sibling to use for historical data instead, so it stops short of explicit alternative routing.

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

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

No annotations are provided, so the description carries the full burden. It does well: it reveals this is a lazy-loaded detail source, that the eager instructions already summarise each area, and what happens with no argument. It stops short of describing the response format/pagination behavior that _offset implies, so not 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?

Purpose is front-loaded in the first sentence, with the topic catalogue following as supporting detail. The topic enumeration is long but each item is load-bearing for a help tool; only the sheer density keeps it from a 5.

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 no output schema and a simple two-parameter surface, the description fully explains what the agent gets for each input class and how to discover available content. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% so baseline is 3, but the description goes beyond the schema by listing accepted synonyms, the full metric/tool roster, and the omit-topic listing behavior. It adds real semantic value on top of an already-documented schema.

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

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

Specific verb ('Fetch the full guidance') plus resource ('behind the server instructions'), scoped as on-demand. It draws a clear boundary against every get_* data sibling by positioning itself as the meta/documentation tool.

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

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

Explicitly states when to call it ('only when you actually need the depth (you usually won't)') and enumerates exactly which inputs map to which content (topics, metric names, tool names). It also discloses the fallback behavior (omit topic to list what's available), leaving nothing 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?

With no annotations provided, the description carries the full burden and discharges it: it discloses the conditional dual-mode return (existing checklist vs. a metrics data bundle that mandates downstream generation), the follow-up chain metadata (threadId, parentInsightId, threadCount), and the refresh semantics. It also proactively rules out outcome/win-rate data, preventing a likely misuse.

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, then layered with usage, exclusions, and return metadata. It is longer than most definitions, but nearly every sentence carries actionable routing or return-shape information, so little is wasted.

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

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

For a 9-parameter, no-annotation, no-output-schema tool, this cooperates well with the siblings, explains what gets returned in both branches, and pins down the follow-up chain fields an agent needs to traverse threads without an extra call.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters, including the report enum, threadId/insightId relationship, and refresh. The description only restates the high-level usage of report/threadId and filtering, adding little beyond what the schema fields already convey.

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 ('the business improvement checklist (the FINDINGS to act on)') and immediately distinguishes it from other insight-adjacent tools by defining insights as observations, not outcomes. An agent can read this and know exactly what get_insights returns versus get_interventions.

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

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

Explicitly routes the agent: use save_insights after generating recommendations, use set_intervention to flip a finding to 'addressed' once a fix ships, and use get_interventions(report: 'outcomes') for win-rate/outcome questions. It also states the refresh trigger and when to use report: 'thread'.

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

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

With no annotations, the description carries the full burden, and it does a lot: it discloses what each report returns (open-work composition, verdict buckets, win rate, interventions under review) and that rows carry baseline + post snapshots with computed deltas when closed. It stops short of stating read-only safety, permissions, or rate limits, so it is strong but not exhaustive.

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?

It is dense but front-loaded with the core statement and the single-source-of-truth claim, then organized by report mode. A couple of parenthetical asides are heavy, but nearly every clause earns its place.

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

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

Given a 10-parameter, no-required, no-output-schema tool with no annotations, the description supplies enough to call it correctly (mode selection, insightId linkage, returned content). It does not spell out the full row shape or pagination, but those are minor given the parameter-level guidance already provided.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning beyond the schema: it interprets the report enum in plain language and gives the intent of insightId ('fixes prompted by a specific finding'). The remaining filters are left to the schema, which already documents them.

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

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

The description states a specific verb+resource ('List interventions... and report their measured outcomes') and explicitly positions itself against the sibling insights tools ('This is the SINGLE source of truth for did it work — insights never carry a verdict'). An agent can distinguish it from get_insights/save_insights 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?

It gives explicit when-to-use guidance per mode: report:'status' for 'where did we get to?' / session start, 'list' for full rows, 'outcomes' for worked vs didn't, and insightId to answer 'how did the fix(es) for this finding turn out?'. Scenarios are mapped to parameters concretely.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the output content of each report and the threshold default, which is genuine value, but it never confirms read-only/no-side-effect behavior, permissions, or pagination semantics beyond what the schema already implies.

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 the first clause, then the report details follow in a structured enumeration. It is dense but every clause maps to an actual report or parameter, with little waste.

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 tool with no annotations and no output schema, the description does substantial work by describing what each report returns. An agent has enough to call it correctly; only cross-tool routing guidance 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% (baseline 3), and the description adds real meaning: it explains what each enum value means and defines low_stock's threshold. It enriches the terse 'Report type' schema entry rather than merely restating it.

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

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

The description opens with a specific verb+resource ('Get inventory analytics') and then enumerates all four report types with the exact metrics each returns. An agent can tell precisely what this tool does and how it differs from adjacent analytics tools like get_product_analytics or get_velocity.

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 implies usage by defining each report (summary, low_stock, out_of_stock, by_location) so the agent can pick the right report param, but it never states when to choose this tool over siblings or any prerequisites/exclusions. Usage is implied 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?

With no annotations, the description carries the full burden and does so: it discloses the three-tier source hierarchy, which tier is canonical vs. slightly inflated vs. last resort, that a `_warning` is emitted on the pixel fallback, that channels use Triple Whale attribution when connected, and that pixel counts undercount. It also flags the important trap of not quoting `_pixelFunnel.cvr` as the store CVR.

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 and dense but nearly every sentence carries routing or source-hierarchy information. The one cost is redundancy: the 'canonical CVR comes from get_metrics_comparison / never quote _pixelFunnel.cvr' rule is stated at least three times (body, 'Use for' clause, Notes), which dilutes the signal.

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?

No output schema and no annotations, so the description must explain the return shape itself, and it does: it enumerates the `funnel`, `_pixelFunnel`, `channels`, ROAS/MER, and `dailyTrends` blocks with their sub-fields. Nothing an agent needs to interpret or safely quote results is missing.

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

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

Schema description coverage is 100%, so the three date/pagination params are fully documented in the schema. The description adds no parameter-level syntax, formats, or default semantics beyond what the schema already states. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

Opens with a specific verb+resource ('Get marketing performance dashboard') and immediately scopes it with 'INCLUDING the canonical checkout funnel.' It explicitly distinguishes itself from siblings by naming get_analytics, get_store_summary, and get_metrics_comparison, so an agent can route correctly 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?

Gives explicit trigger phrases ('checkout funnel', 'where do customers drop off') and an explicit prohibition against manual stitching, plus a routing rule for the CVR figure ('for the actual CVR figure use get_metrics_comparison'). This is when-to-use, when-not-to-use, and named alternatives in one pass.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses a prerequisite (market sync must have run at least once) and the order-attribution logic (Shopify market field for Plus, country-code fallback otherwise), which are non-obvious caveats. It leaves out rate limits or output-shape details, but the disclosed caveats are valuable.

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 report contents are front-loaded before the usage and caveat notes, with a logical flow. It is a single dense paragraph; the caveat sentence is longer than strictly needed but still earms its place by flagging a real prerequisite.

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

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

No output schema exists, and the description adequately covers what each report returns plus the sync prerequisite. Pagination is handled by the schema's _offset description, so nothing critical is missing for correct invocation, though attribution caveats could be elaborated slightly.

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 enriches the 'report' enum beyond the schema by specifying that performance includes revenue, orders, AOV, and revenue share, not just 'revenue by market'. It confirms date-range semantics that the schema already documents.

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 Shopify Markets data') and enumerates exactly the two reports it returns: market definitions (countries/currencies) and per-market revenue performance. An agent can immediately tell this is the geographic-market tool, distinct from the marketing/campaign-oriented 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?

Gives clear context: 'Use this to understand which geographic markets are configured and how revenue is distributed across them.' This tells the agent when the tool applies, though it names no alternatives or when-not conditions relative to the many sibling reporting 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?

With no annotations, the description carries the full behavioral burden and does well: it names the underlying data source, warns that pixel CVR undercounts, and describes the return shape including charts and presentation. It does not state read-only/no-side-effects behavior or rate limits, but for a metrics-reading tool this is a minor omission rather than a serious 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?

The description is long but front-loaded around its primary purpose and usage caveats, and every major section adds decision-relevant information. The Notes section repeats the Triple Whale warning already stated in the body, which is mild redundancy but not enough to undermine an otherwise well-structured description.

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?

There is no output schema, and the description compensates thoroughly by describing the return object keys, the charts array format, and how to use comparison.changes. It also covers the canonical metric definitions and period comparison modes, leaving little ambiguity for an agent to call and use the 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?

Schema description coverage is 100%, so the schema already documents all seven parameters, including dates, comparison enum, and custom comparison labels. The description reinforces comparison types (WoW, MoM, YoY, custom) but mostly restates what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource ('Get core e-commerce metrics') and identifies the canonical CVR source, which clearly distinguishes it from sibling tools like get_marketing_performance and get_connector_data. It also names the metrics returned, so an agent can tell at a glance what the tool produces.

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

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

It explicitly says when to use this tool ('BEST FOR COMPARISONS AND THE CANONICAL CONVERSION RATE') and when not to use an alternative ('Do NOT use Triple Whale pixel CVR... as a stand-in'). It also names the specific alternative tools and explains why they would be misleading, which is unusually strong routing guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the return object keys, chart array shape (grouped-bar specs, 3+ bars), and default rendering behavior, plus where % change captions live. It does not cover permissions, rate limits, or pagination behavior beyond the schema's _offset field, but adds substantial operational context.

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

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

Purpose is front-loaded, and the sentences on return shape and chart defaults earn their place because there is no output schema. It is somewhat dense but not repetitive, and every section adds usable 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?

For a five-parameter metrics tool with no output schema or annotations, the description supplies the missing return-shape and chart-rendering guidance. It does not discuss pagination or failure modes, but the core context needed to call and render the tool is present.

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

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

Schema coverage is 100%, so all five parameters are already documented in the schema. The description mentions comparisons conceptually and references the `changes` object, but adds no syntax, defaults, or format details beyond what the schema provides. Baseline 3 applies when the schema carries parameter 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 and resource ('Get metrics') and scopes it to multiple simultaneous comparisons, with examples that clarify the domain. The 'MULTIPLE' emphasis helps an agent distinguish it from the sibling get_metrics_comparison.

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 concrete example questions that select this tool over a generic metrics call, and its 'MULTIPLE comparisons at once' framing distinguishes it from get_metrics_comparison. It does not state when not to use it or explicitly route to the sibling, so guidance is clear but not exhaustive.

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

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

No annotations are provided, so the description must carry the full behavioral burden. It does not disclose whether the operation is read-only (implied by 'look up'), what happens if multiple identifiers are provided simultaneously, pagination behavior despite having an _offset parameter, or any rate limits. The description provides only superficial behavioral context.

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

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

The description is two sentences that are front-loaded with the core purpose and then detail the identifier options. There is no fluff, though the mention of Triple Whale attribution data could be seen as tangentially relevant.

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

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

Given no output schema and no annotations, the description is adequate for a read-only lookup tool but incomplete. It omits crucial details like whether the tool mutates data, how pagination works (despite _offset), and what happens if no identifier is provided. For a tool with 4 parameters and no structured safety guidance, more context is needed.

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

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

Schema description coverage is 100%, so the schema already fully documents each parameter. The description adds some meaning by explaining that orderName is for user-facing IDs and orderId for Shopify numeric IDs, and that orderIds supports batch lookup, but this is largely redundant with the schema descriptions.

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

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

The description clearly states a specific verb (look up) and resource (a specific order), and details the fields returned (line items with product, variant, SKU, quantity, price, vendor). It does not explicitly distinguish itself from the sibling get_orders tool, which likely lists all orders, leaving a gap in 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?

The description explains when to use each identifier (orderName vs orderId vs orderIds) and mentions a use case for batch lookup (cross-referencing with Triple Whale data). However, it does not state when to use get_order versus get_orders, nor does it provide exclusion criteria.

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

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

No annotations are provided, so the description must carry the full behavioral burden. It does disclose valuable behavior for by_tag (sudden-drop detection, weekly comparison windows, drop output) and by_country comparison blocks, which is strong. But it says nothing about auth, rate limits, data freshness, or behavior for by_status/by_product beyond field names.

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

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

The description is information-dense but reads as one long run-on sentence with nested parentheticals, mixing purpose, per-mode guidance, and example questions. It is front-loaded with the core purpose, which helps, but the density and length hurt scannability.

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 10-parameter, four-mode analytics tool with no output schema and no annotations, the description covers the modes well but omits return-shape expectations (beyond field names), pagination behavior despite _offset, date-range defaults, and safety/auth context. It is adequate but leaves meaningful gaps.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters including tag, limit, compare, lagDays, and lookbackWeeks. The description reinforces a few mode-specific uses (tag focus, compare attach) but adds little syntax or constraint detail beyond the schema. Baseline 3 applies when schema does the heavy lifting.

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

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

The description clearly states the tool returns order analytics broken down by a chosen dimension and enumerates each report mode with specific metrics. It distinguishes its report scope from siblings conceptually, though it does not name a specific sibling tool to contrast with like query_orders vs get_order.

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

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

It provides explicit 'BEST FOR' guidance for by_product and by_tag, including example natural-language questions and when to prefer each mode. It does not, however, state when to use this tool over sibling tools such as query_orders or get_top_products.

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 behavioral burden and does real work: it discloses a plan-tier requirement and a consequential upstream schema change that removes funnel fields, which an agent cannot infer from the schema. It leaves a few minor traits unstated (error behavior on non-Plus stores, result-size/rate behavior), but the critical operational caveats are covered.

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 core capability, then the prerequisite, then the deprecation note and alternatives, then the report catalog. Dense and every sentence carries information, though the mid-description NOTE and the trailing report list make it a long single block rather than crisply segmented.

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?

There is no output schema, and the description partially compensates by enumerating the three report types and what each returns, plus the alternatives for funnel data. Date defaults and pagination are already covered in the schema. What remains thin is the actual shape of returned records and how report selection interacts with productId/sortBy.

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, but the description adds meaning the schema does not: it defines what each report enum value returns (summary = total units/revenue, top_products = ranked, product_detail = daily figures for one product). It also loosely describes sortBy sorting ('by revenue or units sold'), though the schema enum uses 'purchases' rather than 'units sold', a minor wording drift.

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 Shopify product sales analytics — units sold and revenue per product') and even names the underlying source (ShopifyQL). It distinguishes itself from siblings by name, routing funnel questions to get_marketing_performance and get_analytics(ecommerce), so an agent can differentiate it from get_top_products and get_product_health 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 the prerequisite (requires Shopify Plus or Advanced), states what this tool can no longer answer (views, add-to-cart, purchase funnel counts), and names the two alternative tools plus the condition that selects them. This is the when-to-use / when-not-to-use / alternatives pattern in full.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the return fields and even flags a useful quirk (productUrl is a full storefront URL to use directly), but it does not state whether this is a read-only operation, rate limits, whether it spans all connected stores by default, or pagination behavior despite the schema mentioning _pagination.hasMore.

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

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

The description is front-loaded with the core purpose, then lists return fields, then usage scenarios. It is one dense sentence plus a return-value list plus a usage sentence. It is slightly over-packed in the return field enumeration, but there is no wasted text.

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

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

For a read-only tool with a 3-parameter schema and no output schema, the description is adequate but incomplete. It covers return fields and usage well, but without annotations it should have disclosed read-only nature, whether the operation mutates anything, and pagination behavior. The mention of _pagination.hasMore in the schema is a hint, but the description does not connect it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add syntax or constraints beyond what the schema provides for limit, store, or _offset. It does mention a default of 20 for limit and 'omit to query all connected stores' for store, but these are already in the schema descriptions.

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

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

The description states a specific verb (Get) and resource (product catalog) and enumerates the exact data dimensions returned: inventory levels, pricing, cost, margins, status, SEO metadata. This is specific enough to distinguish it from get_products_by_channel, get_product_analytics, and get_top_products, though the distinction from get_inventory is somewhat blurred by the overlapping inventory dimension.

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 lists the questions the tool answers: 'products, pricing, profitability, cost price, stock levels, or SEO/meta tags.' This gives the agent clear trigger conditions for selecting this tool over siblings without guessing.

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

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

No annotations are provided, so the description carries the full behavioral burden and does so well: it discloses the composite score range (0-100), the sort order (attentionScore descending), the default filter behavior (minAttentionScore default 0), the default analysis scope (top 50 by sales over 30 days), and the presence of a `flags` array explaining the score. This is unusually rich behavioral disclosure for a no-annotation tool.

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

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

Front-loaded with the core capability in all-caps, followed by use-case quotes, then mechanism, then return shape, then parameters. Some redundancy ('which products need fixing?' / 'are there any product issues?' / 'which products are performing badly?') but each adds a slightly different nuance. Slightly dense but well organized.

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 6-parameter, no-output-schema synthesis tool with no annotations, the description covers purpose, when-to-use, return shape (signals + flags), sorting, filtering defaults, and scope defaults. An agent has everything needed to invoke it correctly and interpret the result.

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 already 100%, so the schema documents limit, store, _offset, endDate, startDate, and minAttentionScore. The description still adds value by explaining the semantics behind minAttentionScore (set to 30 to see only flagged products) and the default window (top 50 by sales over last 30 days), which reinforces rather than merely repeats the schema.

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

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

States a specific verb+resource ('CROSS-SOURCE PRODUCT HEALTH SCAN' returning per-product reviews + refunds + sales velocity + inventory + composite score) and explicitly distinguishes itself from siblings like get_top_products, get_refunds, get_reviews, get_inventory by naming them as what it replaces. An agent can immediately tell this is a synthesis tool vs. the individual-data 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?

Gives explicit when-to-use trigger phrases ('which products need fixing?', 'what should I look at?') and names the alternative path (stitching the sibling tools manually) that this replaces. The rationale (consistent synthesis, same heuristic) makes the value proposition concrete.

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

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

With no annotations, the description carries the full burden and does well: it discloses the attribution methodology (Triple Whale last-click joined to Shopify order line items), the connection prerequisite, and the degraded mode when unconnected ('unattributed'). It omits rate limits or the shape of the returned rows, which is the only 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 sentences, front-loaded with the core purpose, then qualification, then usage examples. Every sentence earns its place with no 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?

There is no output schema, so the description must convey what comes back; it does this at a conceptual level (per-product channel attribution). Pagination is handled by the schema's _offset, and the main remaining gap is the absence of any statement about the return shape or ordering.

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

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

Schema description coverage is 100%, so all four parameters (limit, _offset, startDate, endDate) are already fully documented with defaults and semantics. The description adds nothing beyond the schema about parameters, making the baseline 3 correct.

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 products) plus the distinguishing dimension (marketing channel attribution), and functionally separates itself from siblings like get_top_products and get_product_analytics. The example questions make the intended output 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?

Gives concrete when-to-use context via example questions and states a hard prerequisite (Triple Whale must be connected). It does not explicitly name or exclude sibling tools, so an agent must still infer the boundary against get_top_products, keeping this just below 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 behavioral burden and does so usefully: it discloses the join scope (only /products/{handle} URLs are matched for two reports; collection and blog pages are excluded) and the ranking formula (clicks × orderCount). It does not mention auth requirements or rate limits, but the core semantics of what is computed and what is silently dropped are clear.

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 join purpose, then a compact enumeration of the three report modes with their returned shape. Dense but every clause carries information; the only mild bloat is the repeated qualification about product-only joins, which could be folded tighter.

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 an 8-parameter, no-output-schema tool, the description does the necessary work of sketching what each report returns (driving queries plus sales/orders/refunds, implied click-to-purchase rate, ranked page lists). It leaves the exact field names of the responses unspecified, which is the remaining gap given there is no 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 parameter descriptions already document defaults and formats, setting a baseline of 3. The prose goes further by explaining which parameters matter to which report (url only for by_url, minClicks/maxSales only for unconverting_pages) and by expanding the bare 'Report type' enum into three meaningful modes.

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 combination ('Join Google Search Console queries with Shopify product sales') and immediately names the reports it produces. The self-positioning line ('answers questions that pure SEO or pure sales tools can't') separates it from the other analytics siblings an agent might otherwise pick.

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 context for each report: by_url when you have a product URL, unconverting_pages to flag SEO-visible-but-not-converting listings, top_pages_with_sales to find high-throughput pages. It stops short of naming a specific alternative tool to use instead or stating exclusions beyond the join limitation.

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

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

With no annotations, the description carries the full burden and does well by detailing what each report returns, including bucket semantics and the out_of_stock signal. It does not explicitly state read-only behavior or mention auth/rate limits, though 'Get' strongly implies a safe read operation.

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

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

The description is front-loaded with the core purpose and then structured by report type. It is dense but the length is largely justified by the complexity of the three reports and the bucket list, though it could be more scannable with bullets.

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 analytics tool with no annotations and no output schema, the description is quite complete: it covers report types, metrics, comparison support, and bucket meanings. It omits explicit read-only/side-effect statements and pagination details, which are either implied or left to the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema. It explains report-specific behavior for summary, top_products, and by_reason, and clarifies compare and sortBy usage. It does not cover _offset or the date defaults, which are only in the schema.

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

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

The description gives a specific verb and resource: 'Get refund/return analytics.' It clearly enumerates the three report types and their contents. However, it does not explicitly differentiate itself from sibling tools like get_top_products or get_product_analytics, 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?

It provides clear usage context with 'Best for diagnosing high refund rates' and explains when to use each report type. It does not name alternatives or state when not to use the tool, so it lacks the explicit exclusions required for a 5.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses that output is pre-generated ranked hypotheses, each containing a supporting signal, a falsifiability check ('what else would be true'), and a next-tool recommendation, plus an explicit caution against asserting causation. It doesn't cover auth, rate limits, or pagination, but the causal-safety framing is meaningful context.

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

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

Four tight sentences, front-loaded with the core purpose and followed by return-structure detail and trigger conditions. Every sentence carries distinct information; nothing is redundant.

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 tool with no output schema and no annotations, the description does the heavy lifting by explaining what the return contains (ranked hypotheses with supporting signals and next steps). Combined with fully-documented params, an agent has enough to call it correctly, though the absence of any safety/auth profile leaves 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 all five parameters (store, dates, comparison enum, pagination offset). The description adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific diagnostic purpose ('why did revenue change?') and enumerates exactly what it bundles: headline metric deltas, product mix shifts, and ranked hypotheses. It clearly differentiates itself from siblings like get_metrics_comparison or get_anomalies by positioning as the consolidated causal-diagnosis tool rather than a raw signal source.

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 trigger conditions — 'Use when the merchant asks why revenue went up or down, what's driving performance, or what changed.' This clearly frames the when-to-use context. It stops short of naming a specific alternative tool or stating when-not to use it, which keeps it from 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 mostly succeeds: it explains the root cause of the discrepancy (ad blockers, consent banners, iOS ATT, 10-30% pixel capture), enumerates returned fields, and defines a severity taxonomy. It stops short of stating read-only/side-effect guarantees or rate/limit behavior, and there is no output schema to lean on.

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, then mechanism, then return shape, then usage trigger — a logical order. It is somewhat dense with parenthetical enumerations, but every clause conveys actionable information 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 read-only, three-param tool with no annotations and no output schema, the description compensates well by describing return fields and the domain reasoning behind the metric. The remaining gap is the absence of an explicit read-only/effect statement and pagination note beyond what the _offset schema already provides.

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 all three parameters (_offset, startDate, endDate) are fully documented in the schema, including defaulting behavior. The description adds no parameter-level detail, 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 (reconcile) and a precise resource (ad-spend numbers between Triple Whale pixel attribution and ad-platform APIs), naming the exact channels covered. No sibling tool in the list does this, so the differentiation is implicit but unmistakable.

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

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

Gives a clear triggering condition: 'Use whenever quoting ROAS — pixel ROAS in isolation is reliably wrong on paid channels with bad pixel coverage.' This tells the agent when to reach for it, but names no explicit when-not case or alternative sibling tool for comparison.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses that notes are authoritative overrides the merchant authored, that they are injected into every store-scoped response, and that direct calls are largely redundant. It stops short of stating access/permission scope or the return shape beyond the _storeNotes equivalence, so not quite 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?

Front-loaded with the core action, and the three quoted note examples earn their space by showing the agent what kind of content to expect. Slightly longer than strictly necessary for a two-parameter read, but 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?

No output schema exists, so the description must cover returns; it does so by explaining that the payload matches the _storeNotes already seen in other responses, and pagination is handled by the schema's _offset description. Access scope and error behavior are unstated, which keeps it from 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% and both parameters are documented in the schema, including the omit-to-get-all semantics and the _offset pagination contract. The description restates the 'or all stores if omitted' behavior but adds no 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?

States a specific verb and resource ('Return all merchant-attached LLM context notes for a store') plus the scope variant when the store argument is omitted. The examples of what notes contain make the resource concrete and distinguish it from data-bearing siblings like get_store_profile.

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 tells the agent when this call is unnecessary ('the same notes are auto-injected into every store-scoped tool response as _storeNotes') and the narrow condition that justifies calling it directly ('a session-opening question'). That is a genuine when-to-use/when-not-to-use rule, not an 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?

With no annotations, the description carries the burden well: it discloses provenance (system-generated from catalog + sales), freshness (~monthly refresh), that merchant corrections are applied on top, and that `_merchantCorrected` fields are authoritative. It stops short of stating permissions, behavior when no data exists, or response size limits, so it is strong but not exhaustive.

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 return contract, then provenance, then usage, then the alternative — a sensible order with no filler sentences. The field enumeration and parenthetical for giftLed are dense but each clause earns its place; it could be tightened marginally but nothing is wasted.

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

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

There is no output schema and no annotations, so the description must convey the return shape itself — and it does, enumerating the profile fields and flagging `_merchantCorrected` as authoritative. With only two fully documented, optional parameters and usage guidance included, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so both `store` and `_offset` are already documented in the schema; the description's 'Omit store to get every store in the workspace' largely restates that. It adds no syntax, format, or edge-case detail for the parameters 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 ('Return what the system understands about a store's IDENTITY') and enumerates the exact content returned: primaryCategory, priceTier, audience, positioning, giftLed, revenue-weighted category mix, and price range. That content signature makes it distinguishable from siblings like get_store_summary or get_store_notes 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 triggers ('use as a session opener to orient yourself before answering', 'when the user asks what do you know about my store?') and names the corrective alternative: 'If the profile is wrong, call update_store_profile.' Both when-to-use and the escalation path are spelled out rather than inferred.

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

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

With no annotations, the description carries the disclosure burden and does meaningful work: it reveals the returned measure set, that comparisons are percentage changes vs the prior period, and that all-time totals are included alongside period metrics. It does not cover permissions, rate limits, or the caveat that today is excluded by default (that only lives in the schema), so a small gap remains.

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?

Effectively three sentences: what it returns, when to use it, and the sibling alternative. It is front-loaded and each sentence earns its place, though the first sentence is a dense em-dash list that could be trimmed slightly.

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?

There is no output schema, so the description must (and largely does) enumerate the return contents, including the comparison deltas and all-time totals. Combined with the sibling routing, an agent has enough to call it correctly; only minor operational details (timezone, permissions) are absent.

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

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

Schema description coverage is 100%, so startDate, endDate, and _offset are already fully documented, including the 'yesterday by default' nuance. The description only refers to 'the specified period' and adds no date syntax or pagination guidance 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?

The description names a specific verb and resource (store metrics from Shopify order data) and enumerates exactly what is returned: revenue, orders, AOV, items sold, discounts, unique customers, plus percent changes and all-time totals. It also explicitly scopes the data source ('Shopify order data ONLY'), which is the key way an agent distinguishes it from the many other get_* 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?

It states the intended use case ('Use this for high-level store performance questions') and names a concrete alternative with the condition that selects it: full cross-source overview → get_complete_dashboard. Both the when-to-use and the alternative are explicit rather than inferred.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses the freshness threshold ('stale if > 36h'), the scope (all stores or a single store), and the per-provider breakdown. It doesn't state whether this is read-only (obvious from 'Report') or discuss caching/rate limits. Without annotations, a small gap remains, but the domain-specific threshold detail is above average.

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: scope, payload contents, and use cases. Front-loaded with the core action, zero restatement of the tool name, no filler. The parenthetical threshold and example are both earning their 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 read-only reporting tool with no output schema and one pagination parameter, the description covers scope, per-item fields, thresholds, and intended diagnostic uses. An agent has everything needed to decide when to call it and what to expect back, without needing return-value documentation.

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 context that the tool 'works for a single store too,' implying the store-scoping parameter isn't listed in the schema and the tool uses server-side context instead. That reconciles the single _offset parameter with the multi-store reporting description, adding value beyond the schema text.

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

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

The description states a specific verb and resource ('Report the health of every connected data source for each of your stores'), and it enumerates exactly what is returned per provider/instance: last sync timestamp, record count, freshness flag, and nullability rates. This is clearly distinct from siblings like get_data_sources (which likely just lists sources) and get_anomalies, so an agent can pick 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?

It gives explicit use cases: 'Use this to diagnose why is metric X showing 0?' and 'to confirm data is current before reporting numbers.' Those are concrete when-to-use triggers tied to a real diagnostic workflow, which is stronger than most siblings that only name a resource.

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

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

No annotations are provided, so the description carries the full burden and does so unusually well: it discloses that values are recomputed from ground truth on every call and never stored, that the status band derives from the forecast interval's optimistic end, and that sub-25%-elapsed periods return 'too_early' instead of a noisy verdict. Each pacing field is enumerated, which is behavioral detail an agent cannot infer from 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-loaded with the core purpose before the field inventory and the honesty caveats. It is long and the pacing-field enumeration is dense, but each sentence adds real information; nothing reads as 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?

There is no output schema, so the description must describe returns — and it does, naming the pacing block and its constituent fields plus the six-value status enum. Combined with the honesty notes and the fallback routing, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema and the baseline is 3. The description adds only a light gloss (store means sub-store key, filters narrow by metric/period/store) and says nothing about _offset beyond what the schema states, so it does not meaningfully exceed structured data.

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

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

States a specific verb (list) plus resource (active targets) and scope (merchant's), then immediately narrows what subset actually has live pacing. It explicitly names the siblings it defers to (get_yoy_monthly / query_metric_snapshots), so an agent can distinguish it from the other ~57 get_* tools 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?

Clear about when live pacing applies (monthly revenue/orders targets scoped to a store) and where to go otherwise, plus how to filter. What's missing is a top-level trigger statement telling the agent when to reach for this tool versus get_forecast or get_daily_metrics, but the routing for its edge cases is 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?

With no annotations, the description carries the full behavioral burden and delivers the highest-value traits: sort order (most-recent-first), the per-event shape (date, kind, store, detail), and that expired/closed items are retained within the window. It omits permission/auth scoping and rate-limit behavior, so it stops 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?

Front-loads the core definition and the alternative-routing rationale before the return-format note, with no filler. The parenthetical event-type list is dense but each item earns its place; slightly long overall.

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?

No output schema exists, and the description compensates by specifying the return ordering and per-event fields. Combined with the full-coverage input schema, an agent has everything needed to call and interpret the result.

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 limit, store, _offset, and the date window. The description only reinforces the windowing concept ('within the window'), adding no syntax or format detail beyond the schema; 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+resource ('merged, date-ordered timeline of everything that happened to the business') and enumerates exactly what it merges: interventions and store-context notes. It explicitly names the sibling tools it replaces (get_interventions, get_store_notes), so an agent can distinguish it 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?

Gives an explicit use case ('line dated events up against a metric movement') with a worked example, and states the alternative it supersedes and why. When-to-use is unambiguous and directly contrasted with the two siblings it consolidates.

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 substantial work: it discloses that margin/SKU/discount appear only 'when cost data is available', that margin is computed only over cost-configured units with a costCoveragePercent, and that compare returns the top 5 rising/falling/new products. It omits anything about permissions, defaults for date range, or pagination/latency behavior.

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

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

Front-loads the core purpose in the first sentence and then layers level-specific detail in order of the enum. It is long and clause-heavy with em-dash asides, but each clause carries information rather than filler, so the density is justified.

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 an 8-parameter, no-annotation, no-output-schema tool this is close to complete: it explains each level's return shape, the cost-data caveat, and compare semantics. The remaining gap is that it never states the implicit date-range default or that startDate/endDate scope the ranking, which an 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema — the variant breakdown fields, the category cost-coverage caveat, and the semantic content of the `comparison` block that the schema only labels generically. It does not, however, explain level defaults or the format expectations beyond the schema's own text.

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

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

States a specific verb+resource ('Get top selling products ranked by revenue or quantity') and then crisply distinguishes the three behaviors keyed off the `level` enum, including what each returns (SKU/discount/margin at variant, revenue/COGS/GP/margin-% rollup at category). An agent can immediately tell this apart from get_product_analytics or get_products_by_channel.

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 guidance for each level: 'variant' to break down by variant, 'category' for category-P&L / margin-by-category questions, and compare for WoW/MoM/YoY trend. It does not name a competing sibling to defer to (e.g. get_product_analytics) or state when NOT to use this tool, 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?

No annotations are provided, so the description carries the full burden, and it does disclose a key behavioral quirk: angle:'product', report:'summary' ignores `days` and is always a fixed trailing-30-day aggregate. It also discloses which params apply to which report. It stops short of describing output shape or pagination behavior in prose, but the schema covers offset paging.

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 two-angle model and organized as a bulleted list matching the two enum values, which is scannable. It is fairly long, but every sentence carries routing or param-scoping information; slight density could be trimmed but nothing 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?

For a 12-parameter tool with two modes and no output schema, the description maps angle→reports→params comprehensively, including defaults and the one report that ignores `days`. An agent can select the correct angle/report combination and supply required params without opening the schema.

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

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

Schema description coverage is already 100%, so baseline is 3. The description adds genuine meaning beyond the schema by grouping parameters per report (leadTimeDays/safetyStockDays only for restock, productId required for trend, maxOrders for stagnant) and stating the days default and its exception. This functional mapping exceeds what the schema alone conveys.

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

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

States a specific verb (Get) and resource (sales-velocity analytics), then enumerates the two angles and their report sets. This distinguishes it from siblings like get_inventory, get_top_products, and get_product_analytics by routing explicitly to the velocity use-case.

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 explicit when-to-use per angle with natural-language question frames: 'what should I reorder and how much?' vs 'a single product's trend or stagnant/dead-stock questions.' It also names the report that is 'the reason to pick this angle,' giving a clear decision path between the two modes.

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

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

With no annotations, the description carries the full behavioral burden and does disclose a critical side effect: it auto-marks the wakeup as triggered if the trigger date has passed, meaning this 'get' is not purely read-only. It doesn't cover idempotency (what happens on a second call) or permission needs, so not 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 front-loaded sentences: purpose first, then the routine workflow, then the side effect. Efficient and well-ordered; the inline call example is slightly verbose but earns its place as a usage cue.

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

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

Given no annotations and no output schema, the description covers purpose, intended workflow, and the auto-trigger side effect, plus hints at return content ('full context and benchmarks'). Satisfies what an agent needs to call it correctly, with minor gaps around return shape and repeat-call behavior.

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

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

Schema description coverage is 100%, so both id and _offset are already documented in the schema; baseline is 3. The inline example get_wakeup({ id: 'abc-123' }) reinforces usage but adds no semantic detail beyond the schema.

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

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

States a specific verb and resource ('Retrieve a single wakeup by ID'), which clearly distinguishes it from the plural list sibling get_wakeups. It does not name that sibling explicitly, but 'single ... by ID' is unambiguous about scope.

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

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

Gives a concrete scenario: invoke inside a Claude routine prompt, call get_wakeup, get context/benchmarks, then run the analysis. This is clear context for one intended workflow, though it doesn't contrast against get_wakeups or state when not to use 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?

With no annotations, the description carries the full burden and does well: it discloses the return composition (pending + triggered within 14 days), the freshness window ('last 14 days, waiting for analysis'), and even prescribes agent behavior (LEAD with fired wakeups, run comparison against saved benchmarks). It doesn't state auth requirements or rate limits, which are the remaining gaps.

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 first two sentences are tight and front-loaded, but roughly half the text is a prescriptive script ('LEAD with them: "I have a scheduled check..."') that is verbose and arguably belongs in agent behavior guidance rather than a tool definition, diluting the core purpose statement.

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

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

Complete for a read-only list tool: purpose, timing trigger, return composition, status semantics, and pagination are all covered. No output schema exists, yet the description explains the return shape in prose, which compensates. Only minor missing context (who can call it, rate limits) keeps it from 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%, so the schema already documents all three parameters including the enum default and pagination semantics. The description adds no parameter-level syntax or edge cases beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (Retrieve) and resource (scheduled wakeups) with clear scope ('for a store'). Distinguishes itself from the singular sibling get_wakeup and from broader list tools like get_timeline by being explicitly about scheduled wakeups.

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

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

Gives a clear when-to-use trigger: 'Call at the start of sessions where the merchant might have pending wakeups due — especially if today's date is at or past a previously scheduled triggerDate.' No explicit when-not-to-use or named alternative (e.g., get_wakeup vs get_wakeups) is stated, but the timing guidance is actionable.

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

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

No annotations are provided, so the description carries the full burden; it discloses the data source ('aggregated live from the Shopify Order table'), the presence of a presentation layer, and that the charts come pre-built and in long/tidy format. It stops short of stating freshness/latency guarantees or any permission requirements, but for a read-only time-series tool the behavioral picture is largely covered.

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?

Reasonably tight and front-loaded: purpose first, then return shape, then the rendering-vs-numbers rule. The chart-explanation sentence ('separate charts because units differ') is slightly verbose but does preempt a design question an agent might otherwise ask.

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 no output schema, the description must explain returns, and it does well (rows/charts/presentation, row fields, chart count and format). The only thin spot is that the default week count and pagination mechanics live solely in the schema, but since the schema covers them at 100% the overall picture 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% (both `weeks` and `_offset` are documented in the schema, including the default of 12 and the _pagination.hasMore workflow). The description adds no parameter meaning beyond that, so the baseline 3 applies – it neither compensates for nor undermines the schema.

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

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

States a specific verb ('Get') and resource ('weekly revenue, orders, and items sold as a time series'), with the weekly granularity distinguishing it from siblings like get_daily_metrics, get_yoy_monthly, and get_timeline. An agent can tell what it produces 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?

Explicit when-to-use ('user asks about trends, weekly patterns, seasonality, or uses show me / how is / pattern phrasing'), an explicit default ('DEFAULT TO RENDERING THE CHART'), and an explicit when-not alternative ('Fall back to numbers from rows only when the user asks for a single specific week'). This is close to ideal routing guidance.

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

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

With no annotations, the description carries the full burden, and it does add real behavioral context: it reads pre-aggregated calendar-month snapshots ('clean and quick') and discloses the response shape. It does not address permissions or limits, but for a read-only analytical tool the provenance and performance notes are meaningful disclosure.

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 core purpose is front-loaded in the first sentence and each subsequent sentence adds distinct value (use cases, return fields, chart handoff, data source, rendering default). It is dense and slightly long, but no sentence is pure 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?

There is no output schema, so the description must explain returns, and it does so well (rows, charts, totals, seeAlso). Combined with clear usage guidance and full schema coverage, an agent has enough to call it correctly, though a note on pagination beyond the schema's _offset would round it out.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema. The description adds no syntax or format detail beyond that (metric snapshot requirement, year defaults, and store/source filters are all in the schema), so the baseline of 3 applies.

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

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

The description names a specific verb and resource ('Month-by-month year-over-year comparison for a single metric') and scopes it to one metric, which implicitly separates it from multi-metric siblings like get_metrics_multi_compare. However, it never explicitly names a sibling or states when to prefer this over get_weekly_trends or get_metrics_comparison, so it falls short of full 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?

Strong when-to-use guidance is given via concrete question phrasings ('how is revenue this year vs last year by month?') and an explicit default action ('DEFAULT TO RENDERING THE CHART'). It lacks any when-not guidance or named alternatives, so it stops 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that the numbers match the dashboard and monthly digest exactly, that the output contains a charts array with multi-series semantics, and the list-mode special behavior. It does not mention rate limits, auth requirements, or pagination beyond the schema's own _offset description.

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 purpose, then examples, then return-value and default-action guidance. All sentences earn their place; the 'SAME numbers the merchant sees' emphasis is somewhat redundant with the earlier 'matches the dashboard and monthly digest exactly' claim.

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 13-param tool with no annotations and no output schema, the description covers purpose, usage triggers, default charting behavior, list mode, and return shape (snapshots + charts array). The schema covers the remaining parameter details, leaving nothing an agent needs missing.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters including the subtle periodKind/periodLength interaction and confidence modes. The description adds only the list/no-args mode and doesn't expand any parameter semantics beyond what the schema covers. 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 (Query) and resource (metric snapshots as a time series), and distinguishes itself from siblings like get_daily_metrics, get_weekly_trends and get_metrics_comparison by scoping to canonical snapshot data plus ready-to-render charts.

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 trigger examples ('show me all CVR snapshots for UK over the last 6 months', 'how has ROAS evolved by month?') and an explicit default action ('DEFAULT TO RENDERING THE CHART'). It also states when to call with no args / list:true for the registry.

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

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

With no annotations, the description carries the full burden and does well: it discloses the 50-row cap, the _offset/_pagination.hasMore paging contract, the response row shape, and that omitting status includes all financial statuses. It stops short of stating permissions/auth requirements or confirming read-only behavior, so it is strong but not exhaustive.

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, trigger examples, and disambiguation are front-loaded in the first two sentences, with operational caveats isolated in a short Notes block. Every sentence carries either routing or behavioral information; nothing is redundant.

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 13-parameter, no-required-args query tool with no output schema, the description covers defaults, caps, paging, and a summary of returned fields, which is exactly what an agent needs to invoke it correctly. The absence of an output schema is compensated by the explicit return-field listing.

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 already 100%, so the baseline is 3, but the description adds real meaning: it explains the operational difference between offset and _offset for paging, ties _offset to the _pagination.hasMore flag, and states that status maps to Shopify financial status. These clarifications go beyond the field-level schema text.

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

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

The description opens with a specific verb and resource ('List individual orders matching filters') and enumerates the filter dimensions plus the sortable fields. It explicitly names the two confusing siblings, get_orders (aggregate) and get_order (single known order), so an agent can distinguish this 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?

It gives concrete trigger phrases ('show me recent orders', 'orders over $500', 'this customer's pending orders', 'orders tagged wholesale') and an explicit DISAMBIGUATION block routing aggregate analytics to get_orders and single-order lookup to get_order. When-to-use and when-not-to-use are both stated.

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

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

With no annotations, the description carries the full behavioral burden and does so: it discloses the idempotency identity tuple, the update-vs-append semantics ('latest value wins', metadata merge rules), and the purely additive many-to-many insight linkage with the removal path. These are non-obvious traits an agent could not infer from the name or 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?

It is long, but it is front-loaded (purpose first, then idempotency, then linkage) and uses labeled sections (IDEMPOTENCY, INSIGHT LINKAGE) rather than prose sprawl. Some material on insight linkage duplicates what the schema's insightId/insightIds descriptions already say, which is the only real waste.

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

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

For a mutation tool with no annotations and no output schema, the description closes every gap an agent needs: what is written, what happens on re-write, how links accumulate and how to remove them, and where canonical keys come from. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real value beyond the schema: it tells the agent to pass canonical registry keys, how to discover them (call query_metric_snapshots with no args or read the error hint), how periodKind+periodLength combine so 'last 30 days' and 'April 2026' don't collide, and why sourceParams matters for reproducibility.

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 ('record one or more structured metric snapshots') plus the domain purpose (time-series analysis). It explicitly distinguishes itself from the sibling query_metric_snapshots and from update_insight, so an agent can route 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?

Gives an explicit trigger ('use this whenever you cite a metric in an insight, weekly digest, or benchmark'), names the alternative behavior it replaces (burying the number in prose), and points to the counter-tool for unlinking via update_insight(unlinkSnapshotIds). When-to-use and when-to-use-something-else are both covered.

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 provided, the description carries the disclosure burden and does well: it reveals the tool persists a report for a team to review ('I've logged that for the team to review') and prescribes the post-call conversational behavior (acknowledge, then offer to debug). It does not state permissions, whether the report is user-visible, or what the call returns.

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 trigger condition and the core action, then post-call behavior. Every sentence is doing work, though the parenthetical example lists plus the quoted acknowledgement make it slightly denser than needed for a single-purpose capture 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 an 8-parameter, 3-required mutation-style tool with no annotations and no output schema, the description supplies the missing behavioral contract: when to fire, that a persistent artifact is created, and what the agent should say afterward. The remaining gap is that it never tells the agent what the tool returns or whether the report is retrievable.

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

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

Schema description coverage is 100%, with enums and per-parameter guidance already documenting category, severity inference, userQuote verbatim handling, and expectedValue. The description's example phrases loosely echo the category enum but add no 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?

The description states a specific verb and resource ('Capture their concern as a structured report') and scopes it as USER-TRIGGERED, which is a meaningful distinction in a toolset full of get_* retrieval tools. It does not, however, distinguish itself from the very similar sibling report_data_issue, which an agent choosing between the two would need.

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 concrete trigger phrases ('this number is wrong', 'doesn't match my Shopify admin', 'why is this zero?') and an explicit ordering instruction: capture BEFORE speculating about causes. That is unusually actionable. It stops short of naming when NOT to use it or pointing to the sibling report_data_issue as the alternative.

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

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

No annotations, so the description carries the full burden and does it well: it discloses the dedupe key (toolName, category, description) so the agent knows repeat reports are harmless, and specifies post-call behavior (continue the original task, don't mention the report). That is exactly the behavioral context an agent needs for a write-like side-effecting 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?

Long but front-loaded: the trigger condition, the exclusion, the examples, and the dedupe/after-call behavior each appear once and in priority order. Slightly verbose, but every sentence contributes a distinct rule.

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 6-param tool with no output schema, the description fully covers invocation intent, routing, and side effects. It does not touch severity or responseSnippet, but those are adequately handled by the schema, so no gap an agent would trip on.

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 including the category and severity enums is already documented in the schema. The description's concrete examples ('15 decimal places', '_currency says EUR but values look like USD') reinforce the category semantics somewhat, but add little beyond the schema 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+resource (autonomous bug reporting into a data-issue channel) and immediately differentiates from the sibling report_concern by name. An agent can distinguish it from report_concern and the many get_* siblings 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 says when to call WITHOUT asking (mechanical/structural issues), when not to (value-correctness, routed to report_concern), and lists qualifying examples. 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?

With no annotations, the description carries the full burden and does so well: it discloses that the call supersedes the previous plan by default, that item completion is DERIVED rather than set, and that the plan persists until the merchant re-plans. This is exactly the mutation/destructive context an agent needs.

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?

Dense but front-loaded, leading with the core purpose and effect before enumerating the three streams. Some content duplicates the schema's own descriptions (e.g. the tackle/check/watch definitions), which is minor redundancy rather than padding.

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 nested-object mutation tool with no output schema, the description covers the essentials an agent needs: item structure, linking rules, derived completion, and replace semantics. Return-value behavior is not covered, but no output schema exists to compensate for it.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning on top: it explains the three item streams (tackle/check/watch), why insightId/interventionId must be linked (derived completion), and the carry-forward semantics behind replacePrevious.

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 precise verb+resource: persist the week's committed plan generated from the get_focus data bundle. This clearly distinguishes it from siblings like save_insights, save_target, and update_focus_item, and names the source tool that feeds it.

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 strong context on when to call it (after get_focus, carrying forward unfinished items with their live state) and the effect of the default replacePrevious=true vs. false. It stops short of an explicit 'when not to use' or naming update_focus_item as the alternative for editing an existing plan.

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 so: it discloses the confirm-before-write requirement ('OFFER... confirm before writing — don't auto-save'), append vs replace semantics via replace:true, thread/parent grouping behavior, that any number can be saved, and that the response returns insightIds in input order usable downstream. This is behavior beyond what the schema states.

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?

Long but front-loaded: the TRIGGER and the core observation-vs-intervention distinction come first, then edge cases (replace, update, grouping), then the RESPONSE contract. Every sentence earns its place by routing behavior an agent would otherwise get wrong.

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?

No output schema and no annotations, so the description must supply workflow context — and it does: trigger, confirmation etiquette, replacement semantics, single-update delegation, insight-vs-intervention separation, grouping model, and the returned payload shape. Nothing material for correct invocation is missing.

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

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

Schema coverage is already 100%, but the description adds cross-parameter meaning: replace:true replaces the existing checklist instead of appending, and parentInsightId/threadId group related findings as one story (finding → re-finding → superseded). It also explains why returned insightIds remove a round-trip through get_insights.

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 (save insights) and distinguishes the concept sharply: 'Insights are OBSERVATIONS (findings to act on)' vs set_intervention for shipped fixes. It explicitly names siblings (set_intervention, update_insight, get_insights, record_metric_snapshot), so an agent can route without opening schemas.

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

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

Gives explicit trigger ('whenever you surface a problem or opportunity'), timing ('AFTER generating recommendations from get_insights data, OR mid-conversation when the user confirms'), an exclusion (don't model 'fix applied' or '30-day check' as insights), and directs single updates to update_insight and full replacement to replace:true.

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

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

With no annotations, the description carries the burden and does well: it discloses that notes persist into future sessions, are flagged as AI-suggested, are reviewable/deletable from the dashboard, and prescribes a user confirmation message. It omits any auth/permission or rate-limit behavior, which keeps it 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?

Front-loaded with purpose and call condition, followed by filtering rules and the post-save message. Dense but every sentence carries instructional weight; the confirmation wording could arguably be trimmed but is operationally useful.

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?

No output schema exists, and the description covers the lifecycle an agent needs: when to save, what gets stored, how it's flagged, and how to report back to the user. Return-value detail is unnecessary here, leaving only minor gaps around error/permission behavior.

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

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

Schema coverage is 100%, so the baseline is 3, but the description's examples map onto the enum values (e.g. 'one B2B customer is a reseller' → business_context, 'we exclude wholesale orders' → excluded_segment), teaching the practical use of categories beyond the schema's terse definitions. It adds no guidance on severity or _offset, so not a 5.

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 ('Save a new store-context note') and bounds the scope to 'something the USER told you that future sessions should know', which distinguishes it from siblings like save_insight and save_focus. An agent can tell immediately what this tool persists and why.

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?

Explicit invocation condition ('Only call this when the user reveals business context the data alone wouldn't show') plus explicit exclusions ('Do NOT save speculation, transient session state, or things already obvious from the data. Skip if uncertain'). Four concrete examples clarify the trigger and effectively route against the read/other-save siblings.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that data is stored in our own DB (not a connected-tool write-back), that pacing is intentionally not persisted, that an existing slot's target is superseded with history retained, and that it should confirm in one line afterward. These are rich, non-obvious behavioral traits.

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 constraint/trigger detail in dense, mostly non-redundant sentences. It is on the longer side, but nearly every clause (currency rule, storage location, supersede behavior, confirmation step) earns its place; minor tightening is possible.

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

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

For a mutation tool with no annotations and no output schema, the description covers what is stored, what is not stored, currency/store constraints, unit semantics, and the post-save expectation. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: money metrics MUST be scoped via `store` (currency reason), targetValue is in MAJOR units (80000 = £80k), and period attaches to the CURRENT period of that type. It only omits the odd `_offset` parameter, which the schema itself covers.

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 ('Store a merchant's GOAL for a metric over a calendar period') with a concrete example. It explicitly distinguishes itself from the read-side sibling get_targets by noting pacing is never stored here. An agent can tell exactly what this does versus get_targets.

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 TRIGGER ('whenever the user states a target/goal/budget for a metric') and clarifies the read counterpart ('pacing ... computed later on read by get_targets'). It also notes this is not a write-back to a connected tool, ruling out a plausible misinterpretation.

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