Nuira

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

Beyond the read-only annotations, the description discloses substantial behavior: the exact breakdown fields, how netSalesGap decomposes, that shares can exceed 100%, that returns count in the refund-issued period, that complete=false understates lines, and what null traffic means. It also explains byWeek extras like lossDays and weakestDays, grossDrivers effects, and the headline table's row rendering. This is far richer than the annotations and materially helps correct invocation and interpretation.

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 every major caveat, and most sentences carry operational weight rather than filler. However, it is a dense run-on paragraph with long clauses, making it harder to scan than a bulleted breakdown of metrics and caveats would be. It is appropriately sized for a complex analytics tool but not maximally concise in presentation.

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 seven parameters, no output schema, and a complex multi-metric comparison payload, the description is complete enough to call and interpret the tool correctly. It covers defaults, date constraints, comparison modes, named comparison periods, sales channel scoping, weekly breakdown behavior, output field meanings, and important caveats like returns timing and complete=false. Nothing critical for correct use 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 baseline is 3, but the description adds operational meaning beyond the schema: it explains the default 30-day behavior when from/to are omitted, requires both dates together, and gives a concrete mapping example for a named comparison ('September with October': from/to October, compareFrom/compareTo September). It also reinforces salesChannel persistence and yoyWeekday guidance for natural weeks. Some of this repeats schema text, so it is strong but not fully additive.

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: comparing Shopify sales breakdowns between a span and its comparison period, line by line with change and changePct. It distinguishes itself from the sibling get_sales_by by saying that product-line netSales can differ and that this tool should be quoted for store totals. It also names concrete use cases such as 'why did sales fall' and 'compare these weeks with the same weeks last year'.

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, including comparative diagnosis and year-over-year questions, and when to prefer get_sales_by. It gives a hard usage constraint: a named month, week, or two dates supplied by the operator MUST be sent here, because without them the tool reads the last 30 days instead of that named period. It also explains that salesChannel should persist once the operator says 'online only'.

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

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

Annotations only say read-only/idempotent; the description adds ordering, the earliestDay history boundary (before which no answer is possible), a truncated flag for result overflow, and the explicit limitation that the actor behind a change is never returned. It also explains the semantics of summary.key, summary.alert and the clientType taxonomy, which the agent cannot get from structured fields.

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 answer ('what was changed... newest first') followed by field semantics and then the date-span rule, so nothing important is buried. It is a dense run-on block with heavy parenthetical nesting, which costs readability slightly, but nearly every clause carries information an agent needs.

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

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

There is no output schema, so the description carries the return-value burden and does so thoroughly: response field names (summary.from/summary.to, changePct, summary.key, summary.alert, clientType, earliestDay, truncated) are all explained. Combined with the date-span constraints, an agent has enough to call and interpret 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 adds real meaning: from and to are inclusive, must be paired, cannot be in the future, and must be populated whenever the operator supplied a concrete month/week/date range. The default-30-day fallback behavior is only stated in prose, not 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?

States a specific verb and resource ('what was changed in the ad and email accounts') across named platforms and enumerates the change classes covered (budgets, status, bidding, targeting, creatives, conversion tracking, sends). The ordering ('newest first') and the sibling distinction from configuration tools like get_campaigns (this is history, not current state) are clear.

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 questions ('what changed', 'why did spend or ROAS move on day X', 'did someone pause a campaign') and a strong exclusion-style rule: a named month/week or two dates MUST be sent as from/to, otherwise the tool silently reads the last 30 days. It does not name a competing sibling tool to route to instead, so it stops short of full alternative 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: coverage is defined as the share of platform campaign spend the rows explain, with the reason it falls below 1 (Google gives age/gender for Search and Shopping only, never Performance Max); unconverted=true flags rows dropped for lack of a currency rate; null conversions means 'not reported', not zero. That is exactly the kind of caveat an agent needs to interpret results honestly.

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 what the tool returns, then caveats, then date rules — a sensible order with every clause carrying information. It is dense and semicolon-heavy, and phrases like 'so say so' are informal, 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?

There is no output schema, so the description carries the full burden of describing the return shape — it lists spend, share, impressions, clicks, conversions, conversionValue, roas and cpa, plus byCampaign/campaigns/coverage/unconverted. For a two-platform, six-dimension breakdown tool with date-range semantics, that is complete enough to call correctly on the first try.

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 semantics on top: from/to must be sent both or neither and never after today, and crucially that omitting them silently yields the last 30 days. It also explains the campaignId provenance (from a prior call's campaigns list). Only the dimension enum is left entirely to the schema, which already handles it well.

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 and resource: 'spend and results split by who saw the ads or where', then enumerates the valid splits per platform (Meta: age/gender/device/placement/platform; Google: device/age/gender/network). That is unmistakably an ad-spend-by-audience tool rather than a sales or catalogue tool, though it never names a sibling (e.g. get_contribution_breakdown or get_google_product_split) to draw the boundary explicitly.

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

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

Gives a strong, actionable directive: a named month, week or two dates from the operator MUST be passed here because the default reads the last 30 days and 'is not that month'. It also tells you to pass campaignId to read a single campaign and that campaigns comes from a first call. What is missing is any explicit when-to-use-this-vs-another-tool guidance against the many breakdown 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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description's job is added context, and it delivers: it warns that cogsCoverageAllTime and marginBasisAllTime describe the entire order history rather than the current period, which prevents a real misinterpretation. It stops short of covering data freshness or staleness, hence 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?

It is dense and front-loaded with the core scope statement before drilling into field-level caveats. The heavy parenthetical detail (productFacts enum explanations, the margin caveat) is justified because there is no output schema carrying that meaning, though a single long paragraph is slightly harder to scan than a segmented one.

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 parameters, the description carries full responsibility for conveying what comes back, and it does so thoroughly, including per-field semantics for productFacts and a cross-tool disambiguation for the all-time vs period margin metrics. Nothing an agent needs before calling is missing.

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

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

The tool takes zero parameters (empty object, additionalProperties=false), so there is nothing parameter-level to document; the baseline for a no-param tool applies. The description usefully focuses its effort on interpreting the returned fields instead.

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?

It states a specific resource ('Everything Nuira knows about this company') and enumerates the exact content domains returned: economics/targets, decision rules, productFacts, suppliers, channels, locations and product lines. This is far more specific than a sibling like get_data_status or get_summary and lets the agent distinguish it without opening a schema.

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

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

It gives an explicit usage rule ('Use for any question about the business itself, what Nuira knows, or where a figure came from') and explicitly names the alternative tools (get_summary, get_product_performance) for the closely related period-coverage question. The when-to-use and when-to-use-something-else conditions 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?

Annotations already declare readOnly/idempotent/non-destructive, so this is clearly a safe read. The description still adds substantial non-structured context: default sort order, that largestFalls/largestRises are pre-ranked, that prior* fields are null when comparable is false, and the important caveat that platform claims overlap and must never be summed into store revenue. It does not discuss pagination, row limits, or what 'the period' defaults to beyond 'last 30 days' being implied.

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, sort order and ranking, then caveats, then use cases, then parameters — a sensible order. It is a single dense paragraph with heavy parenthetical nesting (field lists, null semantics, sibling routing all interleaved), which makes it harder to scan than it needs to be, though almost every clause carries information.

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

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

With no output schema, the description carries the return-value burden and does so: it enumerates spend, claimedRevenue, roas and the prior* counterparts, explains null meanings and the name-null case. Combined with the date/comparison parameter guidance, 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. The description earns above baseline by explaining the intent and coupling rules the schema only states mechanically: compare for last year, compareFrom/compareTo take the place of compare, and the worked example ('September with October'). The 'both or neither, never after today' constraint is repeated from the schema, which slightly dilutes 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?

Opens with a specific verb+resource+scope (every ad campaign across Meta, Google and other platforms, over the period, sorted by largest spend) and names the two sibling tools it is not: get_sales for Nuira's own attribution and get_google_product_split for Google product splits. An agent can distinguish it from the ~45 siblings 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 when-to-use phrasings ('which campaigns spend the most', 'best and worst campaigns', 'how did campaign X do') plus explicit routing to alternatives (get_sales, get_google_product_split). It also states a hard when-to-use rule for the date params: a named month, week or operator-supplied date range MUST be passed here because the default is the last 30 days.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them by decoding the edge states (connected false = Channable not connected, no feeds = nothing linked, google null = Merchant Center not connected) and detailing the actual return contents. This is exactly the behavioral context annotations cannot carry.

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 and dense with a sprawling first sentence, but it is front-loaded with the core purpose and each clause (return contents, usage triggers, edge-state semantics) adds distinct value. Slightly heavier than ideal but not padded.

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

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

There is no output schema, so the description carries the full burden of explaining return values, which it does comprehensively (per-feed coverage, omitted stocked products, conflicts, brand values, Google approval/disapproval and blocking issues). Nothing an agent needs 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?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate beyond the implicit global scope of the read.

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 resource (the brand's linked Channable channel feeds / catalogues sent to Meta, Google Shopping and marketplaces) read against Shopify, and enumerates exactly what it returns. It is clearly distinguishable from siblings like get_channels or get_product_performance because the scope (feed coverage, conflicts, Google verdicts) is stated explicitly.

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

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

The 'Use for any question about channel catalogues, product feeds, Channable, Google Shopping disapprovals...' sentence gives strong, concrete when-to-use triggers. It does not name an alternative sibling or state exclusions/when-not, so it stops short of the top band.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantive behavior the annotations cannot convey: platform claims overlap so they must never be summed into store revenue, a channel with `platform: null` reported nothing rather than zero, and the default window is the last 30 days. These are exactly the interpretation traps an agent would otherwise fall into.

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 purpose and the default-quoting rule before the caveats, and nearly every sentence carries a decision-relevant fact. It is dense with parentheticals and repeats some of the from/to constraints already in the schema, which costs a little tightness but not comprehension.

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 carries the full burden of return-shape disclosure and does it: it defines platform vs Nuira attribution, how measuredRevenue and modeledRevenue compose nuiraRevenue, the previousPeriod.byChannel structure, and largestCampaign with roasWithout. For a 5-parameter read tool with zero required params, nothing an agent needs to interpret results 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%, and the description still adds meaning beyond it: from/to are inclusive, must be sent together or not at all, and never after today; compare drives previousPeriod.byChannel with `previous` as default and last-year options; compareFrom/compareTo override compare for a named comparison period. The only soft spot is the phrasing '`compare` for last year', which is looser than the enum's yoy/yoyWeekday values, but the schema resolves 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?

Opens with a specific verb-and-resource statement: spend, revenue and ROAS per marketing channel, naming the actual platforms (Meta, Google Ads, Klaviyo) and the time scope. It then enumerates the returned fields (platform, platformRoas, nuiraRevenue, previousPeriod.byChannel, largestCampaign), which lets an agent separate this channel-level tool from siblings like get_campaigns or get_email_performance without opening a schema.

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

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

Gives explicit defaults and exclusions: quote `platform`/`platformRoas` by default, quote `nuiraRevenue`/`nuiraRoas` only when the operator asks how Nuira attributes and label it as such. It also mandates a routing rule — a named month, week or explicit date pair MUST be sent as from/to because otherwise the tool silently reads the last 30 days. That is a when-to-use and when-not-to-use statement with an alternative behavior spelled out.

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

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

Annotations already declare readOnlyHint/idempotentHint and non-destructive, so the safety profile is covered, but the description adds the non-obvious mechanic: the link opens Nuira and the user approves access on the provider's screen, and nothing is connected by calling the tool. That is exactly the context an agent needs to avoid telling a user the job is done.

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 return value and followed by usage and the approval caveat; no filler. The first sentence is a little dense to parse, slightly blunting the front-loading.

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 still explains what comes back (a link per source plus connected status) and what happens after the call (user approves on the provider screen). For a one-parameter, annotation-covered tool, 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 0% and the single property is an unexplained enum, so the description has to carry the load; 'Pass source to get one link' supplies the key semantic that omitting the parameter returns links for all sources. It does not describe the enum members, but those are self-describing platform names.

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 the concrete artifact returned (one link per data source) and its two effects: connecting a new source or reconnecting a failing one, plus whether the source is already connected. It also undercuts a misleading name/title by clarifying that calling it does not itself connect anything, so an agent can distinguish it from the read-only status tools in the sibling list.

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 the trigger conditions explicitly: the user asks to connect or reconnect a store, ad account or email platform, or get_data_status reports a source missing or in error. It also names the alternative reading path (pass source for one link, omit for all), so both the when and the variant choice are specified.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuinely new behavioral context: the default period is the last 30 days, bounds are inclusive, and dates may never be after today. It does not describe pagination, freshness, or currency handling, so it stops short of a 5 given there is no output schema to fill that 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?

Front-loaded with the returned fields, then the routing rule, then the parameter constraint — a sensible order with no filler sentences. There is mild duplication of the schema's 'both or neither, never after today' wording, which costs a little tightness but reinforces a correctness-critical 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?

With no output schema, the description compensates by enumerating every returned line item and noting each carries its share of revenue. Combined with the default-period disclosure and the sibling differentiation, an agent has enough to select and call this correctly without further context.

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 format, inclusiveness, and the send-both-or-neither rule. The description goes beyond the mechanics to the business intent — the operator's stated month or date range must be passed here rather than relying on the default — which is meaning the schema does not 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?

The description names a specific resource and its exact decomposition: net revenue, COGS, gross profit, ad spend, contribution after media, each with share of revenue. It also explicitly separates this from get_summary by stating get_summary does NOT carry COGS or gross profit, so an agent can route correctly 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 a direct usage trigger ('any question about margin structure, COGS, gross profit, or what is left after costs'), names the alternative it supersedes (get_summary), and adds a hard rule: a named month, week, or two dates the operator gave MUST be sent here, because otherwise the default 30-day read will not match. Both when-to-use and the failure mode of not following it are stated.

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

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

Goes well beyond readOnlyHint by explaining that the recorded cost is distrusted and estimated, defining the `state` values (check_cost vs corrected) with the remedy for each, and flagging windowCogs as a period-wide denominator. It also discloses the default 30-day window and the 'never after today' bound.

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 nearly every clause carries information (field meanings, state values, date rule). The field enumeration and em-dash chaining make it a dense single paragraph that is harder to scan than it needs to be.

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 naming the returned fields and what each means (realisedUnitPrice, recordedUnitCost vs catalogueCost, units, cogs, costedRevenue, windowCogs). Nothing essential for calling or interpreting it 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 paired `from`/`to` semantics are already documented; the description adds the operational consequence of omitting them ('reads the last 30 days, which is not that month'), which raises the salience of the constraint. It adds emphasis rather than new syntax, so it stays near 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 precise selection rule: variants sold in the period whose recordedUnitCost is at or above listPriceExVat, plus the exact fields returned. That rule separates it cleanly from siblings like get_margin_trend or get_product_performance, which don't isolate cost-above-price cases.

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 three concrete trigger questions ('are my costs right', 'why is the margin of product X so low', 'which products sell below cost') and a hard rule that named months/weeks/date pairs MUST be passed. It stops short of naming an alternative sibling for adjacent questions such as overall margin trends.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), so the description spends its words on behavior the agent could not otherwise know: null means a month has not happened yet rather than zero, atRisk/recentlyChurned expose only opaque ids that must never be rendered as names, counts are authoritative, and suppressed=true must be surfaced. Without an output schema these interpretation rules are essential and are stated explicitly.

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 clause and every subsequent clause carries non-redundant information (field names, null semantics, id caveat, suppressed handling). It is delivered as one very long run-on sentence though, which makes the embedded warnings easy to skim past; breaking the caveats out would improve 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?

With no output schema and no parameters, the description must carry the entire return-value contract, and it does: it names the key structures, explains the vip overlap, the cohort null rule, the opaque-id limitation, and the suppressed flag. An agent has everything needed to call it 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?

The tool takes zero parameters, so there is nothing to disambiguate; the description correctly spends no space on inputs and instead documents output shape. Baseline 4 applies for a parameterless tool.

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

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

States a specific resource and its scope immediately: customer behavior over whole history with no period, then enumerates the exact metric families returned (segments, cohorts90, ltvByChannel, rfm, retention.cohorts). The field-level naming makes it unmistakably distinct from the sibling get_customers, which lists individual customers.

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 'Use for retention, cohorts, churn, loyalty or how often do customers come back' line gives clear topic-based routing, including a natural-language trigger phrase an agent can match. It lacks an explicit exclusion or a named alternative (e.g., 'for individual customer records use get_customers'), which keeps it 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?

Beyond the readOnly/idempotent annotations, it discloses meaningful edge-case behavior: `suppressed: true` means under half of revenue carries a customer id and figures must be withheld, a null CAC means no spend or fewer than 10 new customers and is never zero, `support: null` means no helpdesk connected, and `paidGaps` names excluded platforms. It also states the default window is the last 30 days and that each tile carries a `previous` prior-period value.

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?

Information-dense with almost no filler — every clause defines a metric, a null/suppression rule, or a date constraint — and usage guidance about not dividing ratios yourself is front-loaded. The main weakness is structural: it is one long run-on paragraph where the metric enumeration, the edge-case rules and the date-span rules blur together, making it harder to scan than a bulleted layout would be.

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 carries the full burden of describing return values, and it does so exhaustively — naming nested paths (acquisition.acquisition, acquisition.lapsedAtStart, ltvBands, growth) and explaining null/suppressed semantics. For a 2-optional-parameter read tool, nothing an agent needs in order to call it or interpret the response 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; the description still adds real meaning on top: `from`/`to` are inclusive YYYY-MM-DD, must be sent both or neither, can never be after today, and replace the default 30-day period — with the strong operational rule that an operator-named month or week MUST be passed here. The schema's own descriptions already carry much of this, so the gain is incremental rather than unique.

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

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

The description names a specific resource (customer figures for the current period) and enumerates the exact metrics returned: total/new/returning customers, repeatPurchaseRate, avgLtv, marginLtv, blended CAC, paidCac, ltvBands, growth, acquisition.acquisition, acquisition.reactivated and support. It even disambiguates Shopify's returningCustomers (orders) from returningBuyers (headcount), so an agent knows precisely what it gets 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?

Explicit when-to-use coverage: 'Use for any question about customers, LTV, CAC, repeat purchase, acquisition by channel or LTV ÷ CAC', plus a clear prohibition on self-computing ratios and a rule to send operator-supplied months/weeks/date pairs here. It does not route to any named sibling (e.g. get_customer_lifetime, get_sales_breakdown), so the alternative-selection guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive behavior, so safety is covered. The description adds genuinely useful context beyond them: it discloses what the call surfaces (connection state, freshness, sync progress) and, importantly, the semantic rule that zeros on an unconnected or mid-import store are missing data rather than real figures.

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 sentence and the routing/interpretation guidance follows. The second sentence is long and clause-heavy, but every clause (two triggers plus the missing-data rationale) carries actionable meaning, 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?

With no output schema, the description carries the burden of explaining what comes back, and it does: per-source status, freshness, last successful sync, and import progress. Combined with the usage triggers, an agent has everything needed to call it and interpret the result correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. No parameter guidance is needed or expected.

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

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

The description names a specific resource and scope: 'Which data sources are connected for this brand and whether their data is complete,' and enumerates the per-source fields (status, freshness, last successful sync, import progress). This clearly distinguishes it from the sibling data tools like get_sales or get_summary, which return figures rather than connection health.

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

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

It gives two explicit trigger conditions: 'Call this before reporting figures to someone new to Nuira' and 'whenever other tools return zeros or empty lists.' It also explains the reasoning behind the second trigger, so the agent knows not just when to call but why the result changes interpretation.

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

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

Annotations already declare read-only, idempotent, non-destructive, but the description adds real behavior beyond them: the implicit default 30-day window, inclusive date bounds that cannot exceed today, and the crucial interpretive caveat that attributedComparison is Klaviyo's attribution claim which can explain a drop but never proves causation for a rise. That attribution-semantics warning is exactly the kind of context annotations cannot carry.

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

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

Front-loads what the tool returns and who should use it, then the date-handling rule; every sentence carries functional content. Some sentences (particularly the attribution caveat and the MUST-send-dates clause) are long and packed, which slightly reduces scannability but not correctness.

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 zero required parameters, the description supplies the return contents (revenue, sends, open/click rate per flow and campaign), the default time window, and the comparison output's provenance. It does not describe output shape or whether SMS metrics actually appear given the email framing, but it is complete enough to call 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 coverage is 100 percent, so the baseline is 3; the description adds the semantic consequence of `compare` — that attributedComparison returns Klaviyo-attributed revenue for flows, campaigns, and total across both periods with the delta — which is a result meaning the schema does not convey. The both-or-neither and not-after-today constraints are repeated from the schema, so the gain is modest but real.

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: reads Klaviyo flows and email campaigns for a period, with named metrics (revenue, sends, open rate, click rate) at per-flow and per-campaign granularity. Naming Klaviyo and email/SMS implicitly separates it from campaign tools in the sibling list, but it never explicitly contrasts itself with get_campaigns, so differentiation is inferential rather than stated.

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

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

Gives explicit use cases ('asked about email or SMS performance, or which flow earns the most') and a hard routing rule: a named month, week, or two operator-supplied dates MUST be passed here because the no-date default is the last 30 days. It also signals when to prefer yoyWeekday over the default comparison, covering the main alternative-selection decisions an agent faces.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral content beyond them: that results include historical values, effective/supersession timestamps, provenance, and source document snippets. It does not discuss result size, ordering, or truncation, which keeps it out of the top band.

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

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

Two sentences: the first front-loads what the tool returns, the second handles routing. Every clause ('when it took effect', 'when it was superseded', 'where it came from') maps to a distinct returned field, so 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?

There is no output schema, so the description carries the burden of describing return values, and it does so field-by-field. With zero parameters and annotations covering safety, an agent has everything needed to select and call this tool correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and 4 is the baseline. The schema is trivially covered and the description correctly makes no parameter claims.

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 ('how the figures Nuira holds about this business have changed over time') and enumerates the returned dimensions (value, effective date, supersession date, source, document, snippet). It explicitly contrasts itself with the sibling get_business_profile, so an agent can route 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 names concrete trigger conditions ('what a figure used to be, when it changed, or why Nuira believes it') and names the alternative for the opposite case ('For the values in force today, use get_business_profile'). When-to-use and the alternative are both explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds critical guidance beyond them: goals are saved only in the goals editor by their owner, and the agent must never claim to have set or changed one. It also explains non-obvious semantics like withheld platforms, computed MER, and how `checks` should be interpreted and communicated.

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 and front-loads the resource description before diving into field semantics. Most sentences earn their place given the absence of an output schema, though the volume of backticked field names makes it heavier than ideal.

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 four undocumented parameters, the description still explains the return structure (goals, origins, budgetOrigin/targetOrigin, checks, suggestion bases, withheld platforms) and the vocabulary needed to interpret it. An agent has everything required to both call the tool and narrate its results 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 0%, so the description must carry the full burden — and it does. It explains that `month` is YYYY-MM with the current month by default, and that the three numeric parameters are hypothetical values to be judged against history, which is meaning the schema alone cannot 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?

The description names a specific resource — the month's goals register — and enumerates the exact contents: net revenue, media spend, the computed MER target, nCAC target and per-platform budgets. No sibling tool covers goals, and the field-level detail makes the scope 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?

It gives concrete triggers: use it to judge values the person is considering (by passing netRevenue/totalSpend/ncacTarget) and when asked who set a goal or whether it is Nuira's. No alternative tools are named, but none in the sibling list overlap, so the guidance is sufficient without explicit exclusions.

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

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

Annotations already declare this is a read-only, idempotent, non-destructive, closed-world read, so the safety profile is covered. The description adds real behavioural context beyond that: the 30-day window, the reconciliation of Google's counted purchases against Shopify orders traced to Google, and that every finding comes with the fix in Google Ads.

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 intent is stated up front, but the payload is delivered as one long run-on list of checks stitched together with commas and em-dashes, which is dense to parse. It is not padded with filler, yet the enumeration could be tightened into a shorter, more scannable form without losing meaning.

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 parameters and no output schema, the description must carry the burden of what the caller gets back, and it does so by enumerating each check performed and noting that each finding includes the fix. It stops short of describing the response shape or finding severity, but is otherwise complete for a zero-argument diagnostic.

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

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

The tool takes zero parameters, so there is nothing to document and the baseline is a 4. The description correctly frames the call as a parameterless audit snapshot rather than implying filters or arguments.

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 — checking the Google Ads conversion setup against an audit's criteria — and then enumerates the exact checks (which actions count and get bid on, double-counted purchases, non-purchase actions steering bidding, one-per-click counting, static values, clutter). No sibling tool covers conversion health, and the enumerated scope makes the tool 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?

The final sentence gives an explicit trigger list: any question about Google conversion tracking, conversion actions, primary/secondary conversions, why Google reports so many conversions, or whether Google is optimising for the right thing. It is clear when to use it, but names no alternative or when-not-to-use condition against siblings like get_google_product_split or get_money_flow.

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

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

Annotations already cover safety (readOnly/idempotent/non-destructive), yet the description adds real behavioral context: the break-even verdict logic, that some spend cannot be split by product, and what labelExport reports. It loses a point because it internally contradicts itself on the default window — 'the last 90 days' vs the schema's 'omit both to read the default 30-day period' — which leaves the agent unsure of the true default.

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

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

One dense paragraph: purpose first, then return fields, then the labelExport behavior, then date override and filters. Every sentence carries information, though the long mid-paragraph run-on describing filters could be broken up for faster 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?

No output schema, so the description correctly carries the return-value burden (verdict buckets, spend, Google-reported conversion value, ROAS, unsplittable spend, labelExport flag), and it documents date override and filters. The main gap is the 90-day vs 30-day default discrepancy and the thin coverage of the remaining filter params, but for an 11-param read-only analytics tool it is close to 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 only 18%, so the description must compensate, and it largely does: it names category, collectionId, label (with the 'exact values from a first call's facets' hint), inStockOnly, newOnly, bucket, search, and sort/dir, and even enumerates bucket values and the sort field contributionMargin. It stops short of syntax/format detail for the remaining params, and dir's semantics are only implied by 'sort/dir reorder 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?

States a specific verb+resource+scope: Google Shopping/Performance Max spend per Shopify product judged against each product's own break-even ROAS, with the resulting earn/break-even/lose verdicts. It is immediately distinguishable from siblings like get_product_performance or get_contribution_breakdown because it names the channel, the adjudication logic, and the outputs (spend, conversion value, ROAS, unsplittable spend).

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 ('any question about which products to push or cut on Google, Shopping or Performance Max ROAS by product, or product-level ad profitability'), an exclusion ('Search campaigns are not included'), and a worked routing example ('my best products losing money on Google in category X' = bucket [loses], category [X], sort contributionMargin). Alternatives are implicitly excluded by channel scoping.

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

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

Annotations already declare readOnlyHint/idempotent/non-destructive, so safety is covered. The description adds real value beyond them: the default window is the last 30 days, the span can be overridden, and it discloses what the response contains (including suggested negative keywords and PMax categories) — notable since there is no output schema.

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

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

The scope is front-loaded ('Google Ads search terms over the last 30 days') and the trailing enumeration is dense but each item conveys distinct retrievable content. The single run-on paragraph with a long comma list is slightly heavy, keeping 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, the description carries the burden of describing returns and does so thoroughly, and it documents the optional date-window override and its default. An agent has everything needed 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 100%, and the schema already documents both `from` and `to` with the 'send together or omit both' rule. The description restates that same constraint ('both or neither') without adding format or edge-case detail, so it is a baseline 3.

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

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

The description names a specific resource (Google Ads search terms over the last 30 days) and enumerates the concrete outputs: brand vs non-brand split, per-campaign brand share, no-conversion spend, suggested negatives, converting terms, and PMax search categories. It is unmistakably distinct from siblings like get_google_product_split or get_product_performance.

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 triggers ('any question about search terms, negative keywords, wasted Google search spend, brand vs non-brand, or brand inflating a campaign's ROAS'), which is strong context. It stops short of naming alternatives or when-not-to-use conditions, 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine semantic context beyond that: it explains what the 'untracked count' means (SKUs Shopify does not track, in no band, not a problem) and what the payload contains (days of cover, units left, nearest-to-running-out SKUs). It stops short of noting any size/limit on the returned SKU list.

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

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

Front-loads what is returned, then usage, then the edge-case clarification, then the alternative pointer — a sensible ordering. The untracked-count sentence is slightly wordy ('they are in no band and are not a problem, they are simply uncounted') but each clause does add meaning.

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 convey the return shape, and it does: band definitions, days of cover, units left, the closest-to-running-out SKUs, and the untracked count. No parameter documentation is needed since the tool takes none.

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

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

The tool takes zero parameters, so the schema carries no semantics to explain and the description needn't document inputs. Baseline for a parameterless tool, with no compensating information needed.

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 concrete resource (stock levels per SKU) and enumerates the four output bands with their thresholds, so the agent knows exactly what the tool returns. It also names the sibling get_top_products as a different concern, distinguishing itself without requiring schema inspection.

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 'Use for any question about stock, restocking, or what will run out,' covering the trigger conditions broadly, and routes the adjacent-but-different question (best sellers) to get_top_products. Both when-to-use and the alternative are stated.

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

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

Annotations already declare a safe, idempotent, closed-world read, so the safety burden is lifted. The description adds genuinely useful behavior beyond them: the null-vs-zero distinction ('a null coverage means that area has nothing to measure yet, which is different from a coverage of 0') tells the agent how to interpret empty results, which annotations cannot 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-loaded with the core definition before drilling into per-area meanings, and the trailing null-handling caveat is placed last where it belongs. It is one dense paragraph with an embedded list, which is slightly heavy but every clause (each coverage area plus the null rule) 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?

With no parameters, no output schema, and full annotation coverage, the description carries the interpretive load well: it enumerates the likely return areas and, critically, explains how to read null results. Nothing an agent needs to call or interpret this tool is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly introduces no parameter discussion.

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

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

States a specific resource and its exact semantics: per-area data coverage as a 0-1 share, with each area (margins, customers, catalogue/channels, documents) concretely defined. An agent can tell it apart from sibling getters like get_data_status or get_summary because the description pins down that it reports how much is known rather than the values themselves.

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 trigger phrasings ('what do you know about us', 'how good is your data') and explicitly claims the COGS/cost-coverage question space. It stops short of naming when NOT to use it or pointing at a sibling alternative, which keeps it out of 5 territory.

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

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

Annotations already declare the safe read-only, idempotent, non-destructive profile, so the bar is lower. The description still adds genuinely useful behavioral context — that the output is a monthly time series of two specific margin measures rather than a single value — which is not derivable from the annotations or the empty schema. It does not mention the time window covered or any row limits, so it falls short of a 5.

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

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

Three sentences, front-loaded with what the tool returns before routing guidance, with no filler. Every sentence earns its place: content, when-to-use, and alternatives.

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 parameters and no output schema, the description must convey what comes back, and it does (monthly gross margin and margin-after-spend). It omits the time span or history depth the series covers, which an agent would want to know before promising 'history' to a user.

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

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

The tool takes zero parameters, so the schema baseline is 4 and there is nothing for the description to clarify. No parameter syntax or defaults are misrepresented.

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 resource (gross margin and margin-after-spend) and its granularity (month by month), and explicitly names the two siblings it is not — get_contribution_breakdown and get_vertical_benchmarks. An agent can distinguish it from all 23 siblings 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 trigger conditions ('whether a margin is normal, when it changed, or how it compares with earlier periods') and names the two alternative tools with the conditions that select them (single-period structure, industry range). Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial semantics: `settledFees` null means not reconciled yet rather than zero, no rows means no marketplace is connected, and the default window is the last 30 days. These are non-obvious data-semantics traps that go well past the annotation set.

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

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

It is front-loaded with the metrics and the routing sentence, and no sentence is filler. The metric enumeration is dense and comma-stacked, making the opening sentence hard to parse on first read, but it earns its length by covering null semantics and the date default.

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 only two optional params and no output schema, the description carries the return-value burden itself and does so by defining every field plus the `total` aggregation and the empty-result meaning. An agent can call this correctly and interpret the response without further context.

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 `from`/`to` are already documented as inclusive YYYY-MM-DD, both-or-neither. The description reinforces the consequence of omission (defaults to last 30 days, which is not the month asked about) and the 'never after today' bound, adding practical meaning beyond format rules, though it largely restates the schema's both-or-neither contract.

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 pairing (what each connected marketplace sold and cost over the period) and enumerates the exact metrics returned (gross, fees, takeRatePct, marginAfterFees, settledFees, orders, cogsCoveragePct). It also names the covered systems (Mirakl marketplaces, Channable channels) and the `total` row, which distinguishes it from siblings like get_pnl or get_contribution_breakdown.

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 routing language is present: 'Use for marketplace fees, commissions, take rate or which marketplace is worth it.' It also states a hard condition — a named month, week, or two dates the operator gave MUST be sent here, otherwise the tool silently reads the last 30 days. That is when-to-use plus when-the-default-is-wrong, 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes further by disclosing the result shape (a node/edge network carrying attributed revenue and order count), which matters because there is no output schema. It stops short of mentioning size limits or empty-result behavior.

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

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

Two sentences: the first front-loads the result shape, the second handles routing and exclusions. No filler, no restatement of the title or annotations.

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 parameters and no output schema, the description carries the full load and does so: it explains what the graph contains, what question it answers, and which sibling to use instead. An agent has everything needed to select and 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?

The tool takes zero parameters, so the baseline is 4 and there is no schema semantics for the description to duplicate or compensate for.

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

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

States precisely what the tool returns: channel-to-product revenue attribution expressed as a network of channel and product nodes joined by attributed revenue and order count. It also explicitly distinguishes itself from two named siblings (get_channels, get_top_products), so an agent can pick it 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?

Gives concrete triggering questions ('what a channel actually sells', 'which products a channel's spend is earning') and then names the alternatives with the condition that selects each: get_channels for spend/ROAS, get_top_products for channel-agnostic revenue ranking. Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the safety profile needs no restating. The description adds genuinely useful semantics beyond that (contribution = gross profit minus ad spend, cogsCoverage is a 0..1 share, marginBasis distinguishes measured from blended/entered margins, targetsSource distinguishes operator targets from Nuira defaults), but it omits the one behavioral caveat the annotations do not cover: the silent 30-day fallback is only disclosed in the parameter paragraph rather than as a risk warning.

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 metrics, then routing, then parameters, so the important content comes first. It runs long and packs the return-field catalogue, target semantics and date rules into one dense paragraph, but with no output schema most of that detail is load-bearing 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?

There is no output schema, so the description must carry the return shape itself - and it does, naming every field plus the nested targets object and its actual/target/variance/meetsTarget members. Combined with the metric definitions and date-span rules, 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% and the two date params are already fully documented there, including the inclusive-YYYY-MM-DD format and the paired from/to rule. The description's param text mostly restates the schema; its only added value is the framing that omitting the dates yields a 30-day window that is not the operator's month.

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 ("headline P&L for the current period") and enumerates the exact fields returned (netRevenue, cogs, grossProfit, grossMarginPct, adSpend, contribution, cogsCoverage, marginBasis, targets). It explicitly separates itself from get_contribution_breakdown, so the agent can distinguish the two without reading the 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 phrases ("Use for profit, margin, P&L, 'are we on target'"), names the alternative for the waterfall case (get_contribution_breakdown), and states a hard routing rule: if the operator named a month, week, or two dates, they MUST be sent here or the tool silently reads the last 30 days. That is a when/when-not rule with the failure mode spelled out.

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

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

Annotations already cover read-only, idempotent, non-destructive semantics, so the bar is lower. The description nonetheless adds genuinely non-obvious behavior: the suppressed flag means categories are mostly unset and no breakdown should be reported, and omitting dates silently falls back to the last 30 days. It does not describe the shape of returned rows (dimensions, ordering, top-N behavior), which is the remaining 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 purpose and sibling routing are front-loaded, then the caveat and date guidance follow in priority order, with zero filler sentences. It is slightly dense and the mid-paragraph IMPORTANT block competes with the usage sentence for attention, but every sentence carries unique 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 zero-required-parameter read tool with full schema coverage and no output schema, the description covers what it computes, when to use it, the fallback period, and how to handle the suppressed case. Only the return shape (row fields, ordering, cardinality) is left implicit, which is a minor omission here.

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 already states inclusive YYYY-MM-DD, both-or-neither, and not-after-today, so credit is only for added meaning. The description supplies the operational consequence — omitting the span reads the last 30 days rather than the requested month or week — which turns a format rule into a reason to pass the parameters.

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

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

The description names the specific metrics (revenue, units, margin), the grouping dimension (product category), and the period, then explicitly contrasts itself with get_sales_by for collection/tag/channel splits. An agent can distinguish this from get_product_performance or get_sales_breakdown on the text alone.

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

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

It gives an explicit trigger ('which category or product type drives the business'), an explicit alternative with its own trigger ('for one collection, tag or sales channel use get_sales_by'), and a rule for when the date parameters MUST be supplied versus omitted. That is close to complete 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?

Annotations already cover the read-only/idempotent/non-destructive profile, and the description adds genuinely non-obvious behavior: gross margin returns null when supplier costs are missing and must be reported as unknown rather than zero, plus the default 30-day window and the 'both or neither, never after today' date constraint.

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: metrics and default period first, then the null-margin caveat, then the date parameters. It is slightly dense with parentheticals and the closing clause is a touch emphatic, but nearly every sentence carries operational weight.

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 correctly enumerates the returned figures including the change-versus-previous-period dimension, and it flags the one non-obvious return state (null margin). Needed behavioral and parameter context for a two-param read-only tool is fully 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 the baseline is 3, but the description adds real meaning by stressing the consequence of omitting from/to — the call silently reads the last 30 days, which would be wrong for an operator-specified month. That turns a mechanical schema note into a decision-relevant warning.

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 scope — 'headline catalogue figures for the current period' — and enumerates the exact metrics returned (revenue, units, AOV, gross margin, out-of-stock SKUs, period-over-period change). This clearly separates it from per-product siblings such as get_top_products or get_product_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?

It gives explicit routing guidance ('Use first for any question about how the catalogue as a whole is doing') and a strong when-to-use rule: a named month, week, or date range the operator supplied MUST be sent here. What's missing is naming specific sibling alternatives for the cases this tool does not fit, so it stops short of full 5.

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

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

Annotations already cover read-only/idempotent/non-destructive, yet the description still adds substantial behavior: revenue is before returns and must never be called net sales, bucket grain follows period length, and buckets[i].complete=false marks a partial bucket that must not be read as a drop. It also defines repeatBuyers precisely (2+ orders of the same product), which prevents a plausible misreading.

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 shape and dense but purposeful, with parenthetical guards ('before returns, so never call it net sales') that earn their space. It runs long as a single paragraph with several nested clauses, which slightly taxes scanability for an agent.

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 by enumerating the returned sections (buckets, top-product revenue, lifecycle stage counts, repeatBuyers) and their caveats. Combined with the date-span rules, an agent has everything needed to call it 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 100% and both date parameters already document inclusive YYYY-MM-DD, send-together-or-omit-both, and the 30-day default. The description restates these with emphasis ('MUST be sent here', 'never after today') but adds little semantic detail beyond what the schema already says, 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 (how product sales moved) plus the exact payload: bucketed revenue/units/orders, top-product revenue, lifecycle stages, and repeat buyers. The inclusion of lifecycle stages and repeat-buyer counts makes it distinguishable from adjacent tools such as get_top_products or get_product_performance without opening a schema.

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

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

Gives concrete trigger questions ('which products are growing or declining', 'is product X picking up', 'which products bring customers back') and a hard rule that operator-supplied dates MUST be passed here or the tool silently reads the last 30 days. It stops short of naming a sibling alternative or an explicit when-not-to-use case, which is what separates this 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?

Annotations already cover read-only/idempotent/non-destructive, and the description adds materially: the 14-day before/after structure, a whole-store benchmark for comparison, the four verdict values plus reason strings, and the tally. It also warns that a verdict is association after the change, not causal proof, which guards against a real misreading.

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

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

Front-loads what the tool actually returns, then the when-to-use triggers, then the causal caveat and pending-scope note. Dense but every sentence carries distinct information; no filler or restated title.

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

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

No output schema exists, so the description must carry the return-value burden, and it does — schema of the report, verdict vocabulary, and tally are all described. The behavioral caveats around causality and pending items close out the remaining 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?

The tool takes no parameters, so there is nothing for the description to disambiguate — the baseline of 4 applies. No parameter guidance is needed or missing.

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

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

States a specific, non-obvious verb+resource: the outcome of recommendations already marked done, broken into target-figure windows, store-relative change, verdict, and tally. This is clearly separable from siblings like list_recommendations, which lists rather than evaluates results.

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 — 'whether a change worked', 'results of past recommendations', 'how many improved' — and a scope exclusion ('Pending ones are still inside their 14 days'). It does not name a sibling alternative for the pending-recommendations case, so a 4 rather than 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description is free to add what they cannot: VAT exclusivity, the definitional alignment with Shopify's Returns line, the booking month rule, and the deliberate exclusion of the current part month with the reason ('a part month reads as a drop'). That last point is exactly the kind of surprising behavior an agent needs to avoid misreading a result.

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 sentences, front-loaded with the metric definition, then the boundary rule, then usage, then the alternative. Every sentence carries distinct information; nothing restates the title or annotations.

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 zero parameters and no output schema, the description must carry the full definitional load, and it does: what is measured, over what window, on which basis, and what is omitted. An agent can call it and interpret the result correctly without further context.

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

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

The tool takes no parameters, so the baseline is 4; the description correctly implies a fixed, non-configurable window rather than inviting date arguments. It does not explicitly say 'no filters accepted', which keeps it from 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+resource (refunds per month) and immediately pins the scope: last six complete months, amount refunded net of VAT plus refund count. It also names the sibling it is not (get_sales_breakdown) and the distinct basis (refund month, not order month), so an agent can separate it from the sales 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?

Gives explicit trigger utterances ('are returns going up', 'how much do we refund a month') and routes the adjacent use case elsewhere: 'For one period's returns beside sales use get_sales_breakdown.' Both when-to-use and the alternative are spelled out rather than implied.

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

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

With no output schema, the description carries the full disclosure burden and meets it: it names every returned field (unitsLast30, days of cover, shortfall30, revenueAtRisk, marginAtRisk), explains the run-rate method honestly ('nothing cleverer'), and discloses that restockQuiet suppresses recommendations for specific product classes with an instruction to explain rather than recommend. Row ordering and totalRows are also stated.

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 definition and method are front-loaded in the first clause, and every clause carries information (fields, exclusions, ordering, use cases). It is a single very long run-on packed with parentheticals, which makes it dense to parse even though little 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?

Zero params, no output schema, read-only annotations — the only real gaps would be return-value and method disclosure, and the description covers both thoroughly, plus the suppression cases and row ordering. Nothing an agent needs to call or interpret this tool is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly adds no parameter discussion and instead spends its space on return 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 resource and computation: stock vs demand over the next 30 days derived from the last 30 complete days of sales. The forward-looking framing implicitly separates it from current-state siblings like get_stock_overview and get_inventory_health, but no sibling is named, so an agent must infer the boundary itself.

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

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

Ends with concrete user phrasings — 'what should I restock', 'how much revenue is at risk from stockouts', 'how much will I sell next month' — which gives a clear trigger context. It offers no when-not guidance or named alternative for the adjacent stock/inventory tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the default 30-day window, the inclusive-date and never-after-today constraint, and the `mature: false` caveat that a month's 30 days have not elapsed so its rate can still rise and must not be concluded from. It also prescribes what conclusion to state from `reading`, which is behaviorally important interpretation guidance.

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 trigger, and almost every clause carries information an agent needs, especially since there is no output schema. The cost is a single dense run-on paragraph enumerating many response fields (timing, cohorts, byOrderMonth) that is harder to parse than a structured list.

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 documents the return shape thoroughly — the `gap` decomposition, `reading` enum meanings, `timing` sub-fields, cohort semantics across two years, and the `mature` flag — so an agent can both call the tool and interpret its result without further sources.

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

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

Schema coverage is 100% and the enum descriptions already explain `compare` and `salesChannel`, so the schema does most of the work. The description still adds value by tying parameters to operator language and stating the all-or-neither rule for `from`/`to` and the default-period consequence of omitting 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?

Opens with a specific verb+resource framing: "Why returns moved, from the refunds themselves (exact, not an estimate per product)." This distinguishes it from the sibling get_refunds_by_month by claiming causal decomposition (gap splits, cohorts) rather than a plain refund count.

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 whenever returns are part of the answer") and a hard routing rule for alternatives: without `from`/`to` it reads the last 30 days, so a named month, week, or operator-supplied date range MUST be sent here. It also maps operator phrasing to parameter choices (e.g. 'last year' over weeks → yoyWeekday, 'solo web' → online).

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description goes beyond them with real behavioural constraints — a fixed 7-day window, local-hours bucketing, and DST days yielding 23 or 24 buckets. It stops short of describing shape/ordering of the returned buckets, which keeps it at a 4 rather than 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 definition, then usage, then the data-availability constraint, then the DST edge case. Every sentence carries decision-relevant information and none is filler.

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

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

With no output schema, the description still supplies what an agent needs: window, resolution, timezone basis, DST edge case, and an explicit instruction for the unsupported hourly spend/margin/ROAS case. Nothing consequential is left unspecified for a zero-parameter read 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool applies. No misleading parameter language is present.

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 with explicit scope: 'Revenue per hour of the local day, over the last 7 days.' The hourly/local/7-day framing cleanly separates it from sibling aggregates like get_sales, get_series or get_sales_breakdown without the agent needing to open 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 positive selection criteria ('when the question is about time of day — which hours sell, when a spike happened within a day') and a hard exclusion ('REVENUE ONLY'), plus a fallback behaviour when asked for hourly spend, margin or ROAS. This is explicit when-to-use and when-not-to-use guidance rather than implication.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description still adds real behavioral context: the data source is Nuira's model rather than platform-reported figures, the window is fixed at 30 days, and the credit split is 30/40/30 position-based. It stops short of stating freshness/latency or how returns or unattributed sales are treated.

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 key differentiator (Nuira attribution vs. platform figures) in the first clause and ends with the sibling redirect. The opening sentence is long and clause-dense, but every clause carries distinct information.

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

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

With no parameters, no output schema, and annotations already covering safety, the description is the sole carrier of meaning and does the job: it names the grouping dimensions, the attribution methodology, the multi-touch metric, and the last-touch comparison. Nothing an agent needs to select and call this tool is missing.

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

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

The tool takes zero parameters, so there is no parameter syntax to document and the baseline is 4. The description correctly spends no space on arguments and instead explains the shape of the data returned.

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 (sales performance by campaign and channel, over 30 days) and pins down the data provenance ('NUIRA ATTRIBUTION, not the platforms' figures'). It explicitly separates itself from get_top_products and get_product_performance, so an agent can route 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?

Gives an explicit use condition ('questions about campaigns, attribution, or which channel really earned a sale') and names the two sibling alternatives for the catalogue-sales case. 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?

Goes well beyond the readOnly/idempotent annotations: it explains the netSales vs orderTotal discrepancy, that returns count in the refund period rather than the order period, and that incomplete data understates every line. It does not mention caching, freshness, or latency, but for a read-only reporting tool the disclosed quirks are the ones an agent would otherwise get wrong.

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 resource definition, then the usage trigger, then the semantic cautions, then parameters. Every sentence carries operational weight, though the IMPORTANT marker and the netSales/orderTotal sentence are dense enough to require a careful read; the paragraph is long for a single 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 fills that void by enumerating the reported lines, defining the two competing revenue bases, explaining the `complete` flag, and stating the default period. An agent has everything needed to call the tool and to report its output honestly without further context.

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; the description still adds decision-relevant meaning — from/to are inclusive, must be sent together or not at all, must never be after today, and omitting them silently reads a 30-day window. The salesChannel semantics ('online only', 'solo web') live in the schema rather than the description, which is a minor gap.

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

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

Names a specific verb+resource: Shopify's own Total sales breakdown (gross sales, discounts, returns, net sales, shipping, taxes) for the current period, using the merchant's Shopify definitions. It explicitly separates this from the rest of the product's reporting basis (`orderTotal`), which distinguishes it from siblings like get_sales or get_sales_by.

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 when the question is about revenue in the merchant's own terms, or when the merchant says our number disagrees with Shopify. It also states a hard requirement — a named month, week, or two operator-supplied dates MUST be passed here because the default is last 30 days — and warns against quoting totals as final when `complete` is false.

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

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

Annotations cover only the safety profile (readOnly, idempotent, non-destructive), and the description goes far beyond that: returns are a pro-rata ESTIMATE that must not be quoted as exact, marginPct null means unknown costs (never zero), overlapping collections/tags mean rows must never be summed, an empty label means 'none', partialCollections figures are a floor, and membership is current rather than as-of-order. It also pre-explains why revenue differs from get_summary and what the default period is when `from`/`to` are omitted.

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 front-loaded well with purpose then use cases, and most sentences carry decision-relevant content. But it is a single dense wall of text with long nested parentheticals and no grouping, making it hard to scan for a 14-parameter tool; there is also a stray store-name token ("Nuira") that reads as an artifact rather than instruction.

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 14-parameter aggregation tool with no output schema, the description compensates thoroughly: it enumerates every returned field (revenue, returns, netSales, units, orders, cost, grossProfit, marginPct, share, previousNetSales/changePct), explains total vs storeNetSales and filteredShare, and documents filter failure modes and comparison periods. Nothing an agent needs to invoke it correctly or interpret the response appears 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 carries the parameter documentation and the baseline is 3. The description still adds real meaning the schema does not: the consequence of omitting from/to (silent 30-day default) and the requirement to send operator-supplied dates, plus how `compare` changes each row's payload and how `sort`/`dir` interact with netSalesChange.

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

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

The opening sentence names the verb and resource precisely ("Product sales for the period grouped by product, product type, collection, tag or sales channel") and enumerates the five groupings from the `by` enum. It also draws the boundary against the fixed product tools and against get_summary's order-level revenue, so an agent can place it among siblings 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?

Explicit when-to-use with concrete example questions ('how much did the Special Prices collection sell this week', 'online vs in-store by product'), a when-not ('use for any question the fixed product tools cannot answer'), and a hard rule that a named month/week/date pair MUST be passed or the tool silently reads the last 30 days. It even prescribes recovery when a filter matches nothing (retry with collections.available) or say it does not exist.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real value beyond them by disclosing ordering ('oldest first'), the in-progress month marker ('complete false on the month in progress'), and the shape of rankedByNetSales. It does not disclose pagination, units, currency, or timezone handling for month boundaries, which matters for a calendar-month aggregation.

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: the resource and window come first, then returned fields, then ordering semantics, then the ranked convenience. The nested parenthetical '(default 12, up to 24)' and comma-spliced clauses make it slightly harder to scan than it needs to be, but no sentence is wasted.

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

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

With no output schema, the description carries the whole burden of explaining the return value, and it mostly does: named metrics, sort order, the `complete` flag, and the rankedByNetSales companion array. Missing only edge-case behavior (e.g., months with zero sales, currency/units) for full completeness.

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

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

Schema description coverage is 100%, so the single `months` parameter is already fully documented with default and min/max. The description restates 'default 12, up to 24' and adds only a minor nuance that the range includes the current month — baseline 3 applies.

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

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

States a specific resource and granularity ('Shopify sales ladder per calendar month') and enumerates the metrics returned (netSales, grossSales, returns, orders), which distinguishes it from monthly-agnostic siblings like get_sales or get_sales_by. It stops short of naming those siblings explicitly, so an agent comparing against get_sales_breakdown still has to infer.

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

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

Usage is implied by the shape of the data — a per-month ladder is for trend/month-over-month work — and the 'best month needs no comparing of your own' line hints at a use case. But there is no explicit when-to-use or when-not-to-use versus compare_sales, get_sales, or get_sales_breakdown.

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

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

Annotations already cover the read-only, idempotent, closed-world safety profile, so the description is free to add real behavioral context: the default window is the last 30 days, from/to must be sent together and never after today, and byWeekday carries a days-held count so short spans mislead. What is missing is any sense of how the series is returned (row count, ordering, empty-day handling), which matters for a daily series.

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?

Scope and the key field distinctions are front-loaded, but the prose is dense and runs together several ideas in long sentences, including prescriptive narration rules ('quote it, never work it out') that are more policy than tool description. It could be shortened considerably without losing selection 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?

For a two-parameter, annotation-covered tool with no output schema, the definition covers scope, default window, field semantics, and sibling routing. The main gap is return-shape detail for the daily series, which the absence of an output schema leaves on the description.

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 both date parameters are already documented, but the description adds the consequence the schema only hints at: omitting them silently reads the last 30 days, so an operator-specified month or date pair must be forwarded explicitly. That is genuine meaning beyond the schema rather than a restatement.

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

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

The opening sentence names the specific resource and granularity: daily revenue and spend over the current period. It then names the concrete fields (byWeekday, platformRevenueByChannel, revenueByChannel, spend) and clarifies that these are distinct per-day series rather than period totals, which separates it from get_summary and get_channels.

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 triggers are given ('when something changed', 'a trend or spike', 'one channel on a given day'), and the alternatives are named with their conditions: get_summary for whole-period totals across channels, get_channels for per-channel totals. It also states a hard routing rule — a named month, week, or two dates from the operator must be passed here.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description goes well beyond them: it discloses the 15-row cap versus a full count, the semantics of limitedSoldOut (not a lost sale), variantsOutDuring being null before stockObservedSince, and that a no-match query returns similarTags rather than an empty error. These are real behavioral traits an agent could not infer from the structured fields.

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?

Every clause carries information, but it is delivered as one sprawling run-on sentence with nested parentheses, which makes it harder to parse than a short structured list would be. It is dense rather than wasteful, but the lack of front-loaded structure costs 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?

With no output schema, the description carries the full burden of explaining return shape, and it does: the three stock buckets, per-row fields (unitsSold90d, unitsNow, variants, variantsOutNow, variantsOutDuring), count vs rows, and the similarTags fallback. Nothing an agent needs to interpret the result 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 a baseline of 3 is warranted, but the description adds meaning the schema does not: passing no names means the WHOLE store, and tags are framed as season/range codes like I26. That clarifies the optional-parameter default behavior, which the schema alone leaves implicit.

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 (every active product with a tag/product type, or the whole store) and immediately names what it returns, split into soldOut/partlyOut/inStock. It even distinguishes itself from a sibling by noting a product sold out for a whole period appears here even though get_sales_by cannot list it, so an agent can tell the two apart without opening a schema.

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

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

Gives explicit use-case phrases: 'which of X are out of stock' and 'what sells well and has no stock', plus the get_sales_by contrast that clarifies when this tool is the right choice. It does not address other plausible alternatives (e.g. get_stock_overview, get_restock_forecast), so the routing guidance is strong 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?

Beyond the read-only/idempotent annotations, the description explains the default 30-day period, the inclusive date-span rules, what 'dead stock' means, the ordering and totals behavior of deadStock.rows, and data-gap coverage issues. This is substantive behavioral context an agent needs in order to interpret the results correctly.

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-loaded, first naming the metrics and then giving usage routing and date-window rules. It is appropriately sized for a rich reporting tool, though the single long paragraph and repeated use-case phrasing make it slightly heavier than necessary.

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, but the description explains the returned concepts and key nested fields well enough for an agent to know what the tool provides. It also covers the critical default-period behavior and the sibling alternatives, leaving no major ambiguity for 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 schema already documents from/to syntax and the both-or-neither default behavior. The description adds operational meaning by stressing that a named month, week, or operator-supplied date pair MUST be sent as from/to, otherwise the tool reads the last 30 days and will not match that period.

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 resource and scope: stock and fulfilment figures for the current period, with named metrics such as inventory value, stock cover, dead stock, value by category, and coverage gaps. It also distinguishes this tool from get_inventory_health and get_restock_forecast by naming what each sibling is for.

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 (inventory value, dead or slow stock, overstock, what to clear out, stock by category) and routes adjacent needs to named alternatives: get_inventory_health for what runs out soonest and get_restock_forecast for the 30-day restock forecast. It also gives a crucial when-to-use rule for named months or date ranges.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior on top: null means no sessions were recorded rather than zero, changePoints are expressed in points, sessionsByChannel is empty without GA4 and its total deliberately differs from Shopify's, and byPageType is current-period only. These are exactly the quirks that would otherwise cause misreading of results.

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 metric inventory are front-loaded and there is no filler — every clause carries information about outputs or date handling. The first sentence is however a very dense run-on with nested parentheses, which costs some readability even though 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, so the description carries the burden of describing returns, and it does so thoroughly: each metric group, change-point units, null semantics, empty-GA4 behavior, and the current-period-only scope of byPageType. Combined with the complete input schema and annotations, an agent has everything needed to call and interpret 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% and each parameter is documented there, including the from/to pairing rule, the compare enum meanings, and compareFrom/compareTo replacing compare. The description mostly restates those constraints (both or neither, never after today, 30-day default) rather than adding format or interpretation detail beyond the schema, so the baseline 3 applies.

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

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

States a specific resource (Shopify web sessions funnel) plus the exact measures returned — sessions, purchases, addToCart/cartToCheckout/checkoutToPurchase/conversion rates, stepThatFellMost — and the splits (total, mobile, desktop, byPageType, sessionsByChannel). It does not name a sibling it differs from, so an agent must infer the boundary against tools like get_sales_breakdown or get_channels, which keeps it at 4 rather than 5.

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

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

Gives concrete use cases ('Use for conversion by device, where visitors drop off and where the traffic came from') and a strong conditional rule: a named month, week or two dates the operator supplied MUST be sent as from/to because the default is the last 30 days. It lacks explicit when-not guidance or named alternative tools, so it falls short of 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the default is the last 30 days, `from`/`to` must be sent together, and dates can never be after today. It does not discuss caching or latency, but that is minor for a read-only summary.

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 what it returns, then usage routing, then date semantics – a sensible order with no filler sentences. It is dense and somewhat long, with a bit of overlap between the metric list and the parameter paragraph, but every clause carries information.

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

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

With no output schema, the description compensates by enumerating the returned figures and the comparison-to-previous-period behavior. It also states the default period and the drill-down siblings, so an agent has everything needed 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 100%, so the baseline is 3, but the description adds decision rules the schema does not: both-or-neither for `from`/`to`, never after today, and the critical warning that omitting them silently reads 30 days instead of the requested month. That meaningfully changes how an agent fills the 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?

Names a specific verb+resource and enumerates the exact headline metrics returned (revenue, ad spend, contribution, blended ROAS, new/returning customers, order count, sessions, conversion rate). It is clearly distinguishable from narrower siblings like get_channels or get_series.

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

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

Explicitly says to use this first for any overall-performance question and for new-vs-returning customers, then routes to get_series, get_channels and get_contribution_breakdown for drill-downs. It also states a hard requirement that operator-supplied dates MUST be passed here rather than relying on the default 30-day window.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds behavior those annotations cannot convey: the default 30-day window, the sort order, what `truncated` means and that partial splits should be disclosed, and that null cost/grossProfit/margin signal missing cost data that must never be treated as zero or back-filled. That is precisely the extra context the annotations leave open.

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 resource and ranking, then the return fields, then the usage triggers and date caveats — a sensible order. It is dense and long, but with no output schema the field glossary (revenueShare, rankedRevenue, mostProfitable, highestMargin) is load-bearing rather than padding; only the date-format restatement duplicates the schema.

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 carries the full burden of explaining return values, and it does: the metric set, the pre-ranked `mostProfitable`/`highestMargin` lists, how revenueShare and rankedRevenue work together, and the null/truncation caveats. An agent can answer the question and qualify the result correctly from the definition alone.

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 three params are already documented, but the description still adds operative meaning: from/to must be sent together, never after today, and must be supplied whenever the operator named a period; `limit` defaults to 10 and should be raised on a miss. The remaining schema-covered ground (date format) is restated rather than extended, so not quite 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?

Opens with a specific verb+resource and scope: products earning the most in the current period, sorted by net sales, default 10 / max 50. The enumerated use cases ('which products sell best, which are growing or slowing, which are most profitable, or for a breakdown of revenue by product') let an agent place it against siblings like get_product_performance or get_product_trends without opening a schema.

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

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

Gives explicit when-to-use triggers and a hard routing rule: a named month, a week, or two operator-supplied dates MUST be passed as from/to, because the default read is the last 30 days and 'is not that month'. It also tells the agent when to raise `limit` (when the product in question is not in the top ten), which is a real invocation decision.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the bar is lower. The description adds crucial context beyond annotations: these are reference values, not brand figures, and it discloses the available=false fallback when classification fails. It does not explain how the vertical is classified, a minor 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?

Four tight sentences, front-loaded with what is returned, immediately followed by the critical caveat, then usage guidance and the failure-mode note. Every sentence earns its place.

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

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

No output schema exists, so the description must convey return semantics, which it does thoroughly: reference ranges, the not-brand-data warning, and the available=false failure mode. Complete for a zero-param read 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?

Zero parameters, so baseline is 4. The description appropriately spends its words on semantics of the return values (industry reference vs. brand figures) and the available=false sentinel.

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: returns typical margin and ROAS ranges for the inferred commerce vertical. Distinguishes itself from sibling tools like get_margin_trend by making clear these are industry reference values, not the brand's own data.

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

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

Gives explicit when-to-use guidance: 'Use only to say whether one of the brand's own numbers is normal for its category,' plus a strong prohibition against reporting these as the brand's figures. This routes the agent unambiguously.

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

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

Annotations already declare readOnlyHint/idempotentHint, so safety is covered. The description adds real behavioral context beyond them: the result is a temporal run of days rather than a point-in-time value, which tells the agent what kind of payload to expect.

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

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

Two tight sentences with zero waste, front-loading the core concept and then the usage condition. Every clause earns its place.

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

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

For a zero-parameter read tool with no output schema, the description adequately conveys what is returned (a run of days) and when to call it. It stops short of describing episode boundaries or ordering, but nothing critical is missing 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?

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 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 resource (episodes of a detected change over time) and precisely distinguishes it from the sibling list_insights, which returns a single snapshot. An agent can tell the two apart 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 explicit trigger conditions ('how long something has been happening', 'whether a change is still going on') and implicitly names the alternative (list_insights' snapshot view). It lacks an explicit when-not clause, but the selection condition is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered and the bar is lower. The description still adds real behavioral value the annotations don't: scoping to changes 'still going on', the 'most impactful first' ordering, and that each entry carries its own two-week comparison window. It stops short of describing pagination or limits, which keeps it out of 5 territory.

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 what is returned, then when to use it, then the routing alternatives. Every clause carries distinct information; the window-caution clause is the only slightly dense part and it is genuinely actionable.

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 parameters and no output schema, the description has to carry the return shape itself, and it does: a most-impactful-first list of ongoing changes, each with its comparison weeks. It also covers both the call-time routing decision and the interpretation caveat about windows, so nothing an agent needs is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is no parameter surface for the description to enrich, and it correctly spends no words on one.

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 resource and scope: week-over-week changes and anomalies that are still ongoing, ordered by impact, each carrying its comparison window. It also differentiates itself from siblings by naming list_insight_episodes and list_recommendations, 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?

Explicit trigger ('Use when asked what changed, or why something moved'), plus a concrete precondition ('check each change's window against the period you are describing before connecting them'), plus named alternatives for the two adjacent intents (duration -> list_insight_episodes, action -> list_recommendations). This is about as complete a routing statement as a list tool can carry.

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

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

Annotations already declare this a safe, idempotent, non-destructive read. The description adds real behavioral context beyond that: filtering (dismissed and completed excluded), ordering (highest-ranked first), and the meaning of an empty result. It stops short of pagination or result-size limits, so not a full 5.

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

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

Three tight sentences: what it returns, what it excludes, then when to use it and the alternative. Scoping and the sibling routing are front-loaded with no filler.

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

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

With no output schema and no parameters, the description carries the load well by naming the key return fields (expected value, confidence), ordering, and exclusion rules. An agent has everything needed to call and interpret 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies the project scope is implicit rather than a passed argument.

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

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

States a specific verb (list) and resource (recommendations) with scope: currently open, highest-ranked first. It also distinguishes itself from the nearest sibling by noting that 'what changed' is list_insights' job.

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 ('when asked what to do, or what the biggest opportunity is') and names the alternative tool plus the condition that selects it ('for what changed... use list_insights'). No inference required.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavioral context: results carry a similarity relevance score that must never be quoted as a business figure. It doesn't mention the result cap or empty-result behavior, but that is minor against the annotations.

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

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

Three tight sentences: what it does, when to use it, and a misuse warning front-loaded in each case. No repeated schema or annotation 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?

For a 2-parameter read-only tool with annotations and no output schema, the description covers purpose, routing, and return-score semantics. The remaining gap is practical invocation detail (what `limit` controls and its default) rather than conceptual understanding.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it never mentions either parameter. It conveys that `query` is free-text natural language via the semantic framing, but says nothing about `limit` (range 1-10) or the 2-300 character query bound.

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: finds stored business knowledge (facts, notes, suppliers, channels, products) by meaning. It also scopes the operation to paraphrased questions, which no sibling tool does, so an agent can distinguish it from get_business_profile and the get_* family.

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 trigger and names the alternative: 'Use when get_business_profile does not obviously hold the answer.' It doesn't cover the reverse case (when to prefer other siblings over this one, e.g. get_knowledge_coverage), but the primary routing decision is explicit.

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