MerchantFlow

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about the source ('MerchantFlow's retrieval results') and the return fields, which is useful. However, it does not disclose behaviors like whether the id format is validated, what happens for invalid/expired ids, or pagination/truncation of metadata. With annotations covering safety, a 3 is appropriate.

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 with zero waste. The core action and resource are front-loaded, and the return fields are listed compactly. 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?

For a simple single-parameter read tool with a rich schema, an output schema, and safety annotations, the description is nearly complete. It could mention what happens when the id is not found or invalid, but the schema's warning about not constructing ids manually partially covers misuse. The output schema likely documents the return shape, so the description need not repeat it.

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

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

Schema description coverage is 100%, so the schema already documents the single parameter thoroughly, including the opaque id format and the warning not to construct it manually. The description adds the return fields but no additional parameter semantics beyond what the schema provides. Baseline 3 is correct.

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

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

The description states a specific verb ('Retrieve'), a specific resource ('full record for an opaque document id from MerchantFlow's retrieval results'), and lists the returned fields (id, title, text, URL, metadata). This clearly distinguishes it from sibling tools like search or lookup_order, which have different purposes.

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

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

The description implies usage context: it is for retrieving a full record by an opaque id returned by search. The input schema reinforces this by warning not to construct the id manually. However, it does not explicitly state when to use this tool versus alternatives like lookup_order or get_customer_detail, so it misses the explicit when/when-not guidance that would earn 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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about the impact on P&L accuracy and the returned fields, which is useful but does not reveal additional behavior beyond what annotations and schema provide.

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

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

The description is two concise sentences with no redundancy. The purpose is front-loaded, and the output specification is efficient. Every word 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 an output schema present and full schema parameter coverage, the description adequately covers purpose and output. It could mention the read-only nature explicitly, but annotations handle that. The description is complete for a tool of this simplicity.

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

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

Schema description coverage is 100%; both parameters (include_zero_cost, stale_older_than_days) have detailed descriptions in the schema. The tool description adds no new parameter semantics, so the baseline of 3 is appropriate.

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

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

Description clearly states the verb 'Find' and the resource 'products or variants with missing or stale COGS data', and specifies the output (product titles, SKUs, gap reason). It is specific and distinct from siblings like get_cogs_coverage, though it does not explicitly name alternatives.

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

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

The description implies usage for P&L accuracy monitoring but does not explicitly state when to choose this tool over related ones like get_cogs_coverage or get_item_cogs. The parameter schema offers some guidance (e.g., include_zero_cost, stale_older_than_days), but the description itself lacks clear when-to-use or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it groups orders by email hash, which is a useful algorithmic detail, but it does not discuss limitations (e.g., customers without email hashes) or output specifics. No contradiction, but the added transparency beyond annotations is modest.

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 a single, well-structured sentence that front-loads the core action ('Group orders by customer email hash') and then states the purpose. Every word earns its place; there is no filler or repetition.

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

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

Given the low complexity, a rich output schema, well-documented parameters, and complete annotations (read-only, idempotent, non-destructive), the description covers what the tool does and how. The output schema handles return-value details, and the description supplies enough context for correct invocation without missing prerequisites or vague warnings.

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 input schema provides 100% description coverage, with both 'limit' and 'min_orders' fully explained including defaults and ranges. The description does not repeat or elaborate on these parameters, so it adds no semantic value beyond the schema. The baseline of 3 applies.

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

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

The description uses a specific verb ('Group orders') and clearly states the goal: finding customers under multiple names or phone numbers. This distinguishes it from siblings like list_customers or get_customer_detail, which would not detect duplicates, so an agent can tell it apart without inspecting 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?

The description clearly implies when to use the tool (when duplicate customer identities are suspected) and specifies the detection mechanism (email hash). It does not explicitly name alternatives or state when not to use it, but the unique purpose and clear context make the intended usage evident.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful operational behavior beyond annotations: dates default to the report's own timeframe ending today, and narrower ranges reduce truncation. No contradiction with the annotations.

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

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

Two front-loaded sentences with no filler. The core purpose appears first, followed by the essential selector and date behavior. 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?

With a fully described 5-parameter schema, an output schema, and annotations covering read-only/idempotent behavior, the description is complete enough to call the tool correctly. It adds the remaining non-obvious context: report scope, date defaults, and truncation behavior.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context beyond the schema: 'exactly one of report_id and template_key' clarifies mutually exclusive selection, and 'narrower ranges reduce truncation' gives practical date-range guidance not present in the schema.

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

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

The description states a specific action ('Generate the data for any report over a date range') and a clear resource ('any report'), with the dashboard comparison anchoring its meaning. It differentiates itself from the many metric-specific get_* siblings by covering saved/custom reports and built-in templates.

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

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

The description implies this is the general report-data tool ('the same numbers the dashboard shows') and explains the report selector, but it does not explicitly say when to prefer generate_report over the get_*/run_* siblings or when not to use it. Usage context is present but 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: Klaviyo is an owned channel with spend=0 by design and an is_owned_channel marker, and revenue is what each platform reports for itself (self-attributed). These details go beyond the schema and annotations and help set expectations about data semantics.

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 with no fluff. The first sentence packs the core function, scope, and key metrics; the second explains a critical edge case (Klaviyo spend=0). Information is front-loaded and every clause earns its place.

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

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

Given the output schema exists and the annotations cover safety, the description is largely complete: it lists platforms, metrics, grouping options, and the Klaviyo owned-channel caveat. It could go slightly further by noting how rows are aggregated or whether zero-spend platforms are excluded, but these are minor gaps and the core information needed to call the tool correctly is present.

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

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

Schema description coverage is 100%, so parameters are already fully documented. The description reiterates the group_by values (platform, campaign, country) and platform list, but adds no new parameter-level semantics. Baseline 3 is appropriate because the schema does the heavy lifting and the description contributes little beyond what is already structured.

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 action ('Get'), a specific resource ('paid and owned channel performance'), and enumerates the exact platforms and metrics involved. It clearly distinguishes this tool from siblings like get_channel_roas or get_revenue_breakdown by covering multiple ad platforms, including owned Klaviyo, and listing metric types.

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

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

The description implies usage (when needing cross-platform ad performance across the listed channels) but does not explicitly state when to use this tool versus alternatives such as get_channel_roas or get_date_range_summary. It does not name any sibling or provide exclusions, leaving routing largely 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, and non-destructive behavior, so the safety profile is covered. The description adds useful context about the data source (MerchantFlow) and anomaly categories, but it does not disclose operational details like ordering, pagination, or limits; these are partially mitigated by the 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?

A single, front-loaded sentence with no filler. The parenthetical examples add valuable specificity without bloating the 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?

For a simple read-only query with two optional params, an output schema, and rich annotations, the description is largely complete. It could be slightly stronger with a note about when to use it versus sibling anomaly-adjacent tools, but nothing critical is missing for a correct call.

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

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

Schema description coverage is 100% and both parameters already have clear descriptions. The tool description adds no extra parameter-level meaning beyond the schema, which fits the baseline of 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 clear resource ('recent anomalies detected by MerchantFlow') with concrete examples that define what counts as an anomaly. It is specific enough to separate this tool from generic getters, though it does not explicitly differentiate it from sibling reporting tools like get_recent_activity.

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?

No guidance is given on when to prefer this tool over alternatives, nor are any exclusions or related tools mentioned. The description only restates the action, leaving the agent to infer when 'get anomalies' is the right call relative to the many sibling reporting tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about the data scope (burn rate windows, runway) but does not disclose additional behavioral details such as authentication requirements, rate limits, or error handling. Given annotations carry the safety burden, a 3 is appropriate for the added context.

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

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

A single, compact sentence that front-loads the primary output (current bank balance) and then lists the secondary metrics. There is no redundant or filler text; every clause conveys essential information about the tool's output.

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

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

With an optional parameter, a full output schema, and annotations covering safety, the description provides sufficient information for an agent to understand what the tool returns and how to invoke it. The parameter's optionality and defaults are in the schema, and the output schema defines return values, so nothing critical 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 parameter is fully documented in the schema, including the default behavior and how the largest window affects burn history aggregation. The description mentions '30/60/90 days' but does not name or explain the parameter beyond what the schema already provides. This meets the baseline for high schema coverage.

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

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

Description clearly states the tool retrieves the current bank balance, burn rate over 30/60/90 days, and projected runway in days. This is a specific, action-oriented verb ('Get') with a clear resource and distinct outputs, differentiating it from sibling tools like get_pnl_summary or get_cac_payback which focus on other financial metrics.

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

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

The description implies usage context (financial health check) but does not explicitly state when to use this tool versus alternatives, nor any exclusions or conditions. Since it is a distinct getter for bank data among many getters, the purpose itself provides implied guidance, but the lack of explicit comparison or alternative routing leaves some ambiguity.

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, so the safety profile is covered. The description adds context about low-volume noise filtering, but this is already largely present in the schema description for exclude_below_units, and no additional behavioral details like tie-handling or data completeness are provided.

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 concise sentences, front-loaded with the core purpose, followed by rationale and a key filtering capability. Every sentence contributes meaningful information with no fluff.

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

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

Given a simple list-style tool, a full output schema, and rich parameter descriptions, the description is nearly complete. It could slightly improve by explicitly contrasting with get_top_products, but nothing essential 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?

Schema description coverage is 100%, with each parameter already well-described including formats, defaults, and semantics. The description's mention of a 'minimum units filter' and 'bottom N' adds narrative framing but no new technical details beyond the schema.

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

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

The description states a specific verb ('Get'), a concrete resource ('bottom N products'), and the ranking basis ('by profit or margin'). It clearly identifies the tool's purpose of finding losing SKUs and implicitly differentiates itself from siblings like get_top_products.

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

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

It provides a clear use case: 'Useful for finding SKUs that are losing money,' which tells an agent when to call this tool. However, it doesn't explicitly name alternatives or state when not to use it, so it lacks exclusionary 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'overall' aggregation qualifier but otherwise does not explain calculation basis, segmentation, or response behavior; with annotations present, this is adequate but minimal.

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

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

A single 13-word sentence leads with the resource and scope, with no filler or redundant restatement of the title.

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

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

For a simple read-only metrics call, the complete parameter schema and available output schema cover the necessary detail. The description is enough to invoke and scope the call, though the exact meaning of 'payback metrics' is left to the output schema.

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

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

Schema description coverage is 100%, and both parameters are already documented with format, timezone resolution, and inclusive bounds. The description adds no parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific action ('Get'), a specific resource ('overall customer acquisition cost and payback metrics'), and a scope ('for a date range'). The resource is unique among the sibling tools, so an agent can identify it without inspecting 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?

The description provides no guidance on when to prefer this tool over related metrics tools such as get_ad_performance, get_channel_roas, or get_ltv_summary, and no exclusions or prerequisites. The date-range wording only restates what the input schema already encodes.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the non-additive nature of platform-reported figures, the fact that Meta and Google may double-claim orders, and that MerchantFlow-attributed revenue is null in this result. This goes beyond the annotations and helps the agent interpret 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?

Three sentences with zero waste. The core purpose is front-loaded, the optional comparison is stated, and the critical non-additivity caveat is placed at the end where it can be absorbed without obscuring the main function. 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?

The description is complete for a read-only analytics tool with a rich output schema. It explains the key metric (blended MER), the per-platform breakdown, the optional comparison, and the critical interpretation caveat (non-additive, null MerchantFlow revenue). The only minor gap is not describing the exact output shape, but the output schema exists and covers that.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds context about the compare_to parameter ('optional comparison to the previous period') and the date range, but does not add syntax or format details beyond the schema. Baseline 3 is correct when the schema carries the parameter documentation burden.

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

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

The description states a specific verb ('Get'), a specific resource (blended MER and per-platform spend over a date range), and adds a distinctive scope (optional comparison to previous period). It clearly distinguishes itself from sibling tools like get_ad_performance or get_revenue_breakdown by naming the exact metrics and the non-additive caveat.

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

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

The description implies when to use it: when you need blended MER and per-platform spend with optional period comparison. It does not explicitly name alternatives or exclusions, but the specificity of the metrics and the caveat about non-additivity give clear context. A 4 is appropriate because it lacks an explicit 'use this instead of X' statement but is otherwise 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=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context about the computation scope (date range, default last 30 days) and report contents (coverage of catalogue, units, revenue, margin distribution, missing-cost products), which enriches behavioral understanding beyond the annotations.

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

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

The description is a single, well-structured sentence that front-loads the core action ('Report how much... is covered') and efficiently includes key output dimensions. No filler or redundant phrases.

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 an output schema exists and parameters are fully documented, the description provides a sufficient overview of the report's scope and contents. It could mention edge cases or data handling, but these are not necessary for correct invocation given the rich schema and annotations.

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

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

Schema description coverage is 100%; both start_date and end_date are fully documented with formats, defaults, and timezone behavior. The description only restates the default date range and adds no further parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Report how much of the store's catalogue, units sold, and revenue is covered by COGS data.' It also details output components (margin distribution, top missing-cost products), making it clearly distinct from siblings like get_item_cogs or list_cogs that likely return raw COGS 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?

No guidance is provided on when to use this tool versus alternatives such as find_cogs_gaps or get_item_cogs. The description implies it is a coverage overview but does not state conditions or prerequisites for choosing it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'over time' aspect and the cohort month/week grouping, which is somewhat behavioral. However, it does not disclose additional details such as pagination, result limits, or handling of missing data. Given annotations, this is acceptable but not rich.

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

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

The description is a single concise sentence with no redundant words. It front-loads the core action and immediately lists the key output metrics and grouping options. Every element earns its place, and there is no filler.

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

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

Given that an output schema exists (which presumably describes the return format), the description does not need to explain return values. The essential aspects for calling the tool—what it returns and the parameters—are covered by the schema. The description provides a clear high-level overview. The only minor gap is the lack of explicit usage context, but for a read-only query tool with rich schema and annotations, this is adequate.

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

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

Schema description coverage is 100%, so all parameters are already documented in the input schema. The description only reiterates the metric names and period granularity, which are already present in the schema's enum descriptions. It adds no new semantic information beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Get' and the resource 'customer cohort analysis', and lists the key metrics (LTV, repeat purchase rate, revenue) and time granularity (month/week). It is specific and unambiguous, but it does not explicitly differentiate from sibling tools like get_ltv_summary or run_repeat_purchase_rate, which could overlap in purpose.

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

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

There is no guidance on when to use this tool versus alternatives. For example, it does not explain when to prefer cohort analysis over a simple LTV summary or repeat rate report, nor does it mention any prerequisites or context. The agent is left to infer usage from the tool name and schema.

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, and non-destructive safety profile. The description adds behavioral context beyond that: the default last-30-day range, conversion into one reporting currency, and the multi-store plan requirement. No contradiction with 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 short sentences that front-load the core purpose and scope, then mention the optional breakdown and the prerequisite. There is no filler, repetition of the schema, or unnecessary detail.

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 that all parameters are optional, richly described in the schema, and an output schema exists, the description provides the remaining operational context: default date range, currency conversion, per-store mode, and the plan requirement. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description lightly reinforces per_store and reporting_currency, but it does not add meaning beyond what each parameter's schema description already provides.

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

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

The description states a specific verb ('get'), a concrete resource ('combined profit and loss across every linked store'), and key qualifiers: date range, currency conversion, and the per-store breakdown option. It clearly distinguishes itself from single-store P&L tools by emphasizing 'across every linked store' and 'combined'.

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

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

The description gives a clear prerequisite ('Requires a plan covering more than one store') and explains when to set per_store. It does not explicitly point to an alternative tool for single-store P&L, so the when-not-to-use guidance is implicit rather than fully 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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds valuable behavioral context beyond annotations: customer name and email are partially redacted, and order history is capped at the most recent 200 orders. No contradiction with annotations.

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

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

Three concise sentences with zero fluff. The core action is front-loaded, followed by output scope and identifier provenance, and each sentence contributes 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?

For a single-parameter, read-only tool with a rich output schema and comprehensive annotations, the description fully covers redaction, the 200-order cap, and identifier provenance. Nothing essential for correct invocation is missing.

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

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

Schema covers the only parameter (customer_id) at 100%, giving the source as 'from list_customers.' The description reinforces this by saying the id comes from the customer lifetime value list, but that's a minor addition rather than substantive semantic enrichment. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Get') and resource ('lifetime value detail for a single customer'), and enumerates the exact fields returned: net profit, revenue, revenue, CAC, tenure, and order history. This clearly differentiates it from aggregate siblings like get_ltv_summary and direct list tools like list_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?

It provides clear context: the tool is for a single customer and requires the customer id from the customer lifetime value list. However, it doesn't explicitly name alternatives or state when not to use this tool, so it falls just short of full exclusionary 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description aligns with these. The description adds useful context about arbitrary date ranges and high-level aggregation, but it does not disclose additional behavioral caveats such as how data is aggregated or whether results are cached.

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 a single, front-loaded sentence that names the tool's purpose, the metrics involved, and the intended use case without redundant words. It is concise, structured, and scannable.

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 well-documented parameters and an output schema present, the description plus schema provide enough information for an agent to invoke the tool correctly. It lacks explicit sibling differentiation, but that is not essential for correct invocation.

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

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

Schema coverage is 100%, with both start_date and end_date fully documented including format, timezone resolution, and inclusivity. The description adds no additional parameter-specific meaning, which is acceptable because the schema already carries the load.

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

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

The description clearly states that the tool returns a high-level summary of specific metrics (revenue, profit, orders, ad spend, top metrics) for an arbitrary date range. It conveys the verb and resource well, but it does not explicitly differentiate itself from similar sibling tools like get_pnl_summary or get_revenue_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?

The phrase 'suitable for quick time-period comparisons' gives clear usage context, indicating when an agent would choose this tool. However, it does not provide explicit when-not-to-use guidance or name alternatives among the many overlapping summary 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 cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context: rolling timeframes are pre-aggregated and fastest, while explicit dates are computed live. No contradiction with annotations exists.

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 with no filler. The core metrics and the key parameter tradeoff are front-loaded, and every clause earns its place.

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

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

Given the output schema and rich annotations, the description covers the essential purpose, returned metrics, and the main parameter behavior. It is complete enough for correct invocation, though it does not discuss pagination or sort defaults, which the schema already documents.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful cross-parameter semantics by explaining the performance difference between timeframe and explicit start_date/end_date. This goes beyond individual schema property descriptions and helps the agent choose the right parameter combination.

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 uses a specific verb and resource: 'Get per-discount-code margin metrics', then enumerates the exact fields returned. This level of detail clearly distinguishes it from sibling tools like get_ad_performance or get_pnl_summary.

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 clear context for selecting between pre-aggregated rolling timeframes and a custom live-computed date range, including the performance tradeoff. It does not explicitly name sibling alternatives or exclusion criteria, but the usage context is practical and 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context about what the result includes ('including recurring expenses and CAPEX amortisation') and the breakdown dimensions. There is no contradiction with 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?

The entire description is one tight sentence that front-loads the verb and resource, then adds only the two most informative details (breakdown dimensions and inclusion of recurring/amortisation). Every clause earns its place, and there is no redundant 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?

The tool is a read-only filtered list with an output schema, and the annotations cover safety, so the description's single sentence is close to sufficient. The only real gap is the absence of usage-routing guidance relative to sibling tools, which is captured separately. For an agent deciding whether the tool fits, the description plus schema and annotations are enough.

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%; the schema already documents start_date, end_date, category, and include_capex with formats and defaults. The description does add the 'by category and vendor' framing, but that more describes the output than the parameters. Baseline 3 applies because the schema carries the parameter documentation.

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 uses a specific verb ('Get') with a named resource ('OPEX and CAPEX expenses') and defines the output breakdown ('by category and vendor') over a date range. It also names unique inclusions ('recurring expenses and CAPEX amortisation') that set it apart from siblings like get_revenue_breakdown or get_pnl_summary. Even without naming a sibling explicitly, the content clearly identifies what this tool returns.

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

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

The description implies the usage context (when an expense breakdown is needed) but gives no explicit 'use this instead of X' guidance or exclusion boundaries. Alternatives like get_revenue_breakdown or get_combined_pnl are not mentioned, leaving the choice to inference. This is better than nothing but below the explicit routing bar.

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, covering the safety profile. The description adds context about output content (last sync time, errors) but reveals no behavioral traits beyond what a read-only status query implies.

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

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

One sentence with the action upfront, followed by the integration list and the two output components. 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 zero parameters, rich annotations, and an output schema present, the description is complete for invocation. The enumeration and mention of errors/last sync cover what the response contains; the output schema handles detailed fields.

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

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

There are zero parameters and the schema has no properties, so there is nothing for the description to add. The 0-parameter baseline of 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?

Description starts with a specific verb ('Get') and a precise resource ('connection status of all integrations'), and enumerates the exact integrations. This scope clearly distinguishes it from sibling status tools like get_mca_status and get_north_star_status.

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

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

The description implies use when a global integration-health check is needed (all integrations, last sync time, errors), but it never states when to prefer this tool over siblings or when not to use it. There are no exclusion conditions or alternative tool mentions.

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

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

Annotations already establish the tool is read-only and idempotent. The description adds useful behavioral detail beyond that: it returns both current COGS and full cost history, and on_date changes the effective valuation date. This is meaningful context without contradicting 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?

The description is two sentences with the primary action and scope front-loaded, followed by the identifier options and optional date behavior. Every sentence earns its place and there is no filler or redundant explanation.

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

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

For a read-only single-item lookup with a rich input schema, detailed annotations, and an output schema, the description covers what the tool does, how to identify the item, and the optional historical-date behavior. No additional context is needed for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters in detail. The description mostly restates the schema's identifier guidance and adds only a small clarification about variant_id being the commerce platform's id, which is already present in the schema. It therefore adds little beyond the structured data.

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

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

The description opens with 'Get the current cost of goods sold and full cost history for one item,' which names a specific verb, resource, and scope. It further clarifies the three accepted identifiers, making it easy to distinguish from siblings like list_cogs or get_cogs_coverage.

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

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

The description clearly scopes the tool to a single item and explains the optional on_date behavior, which gives strong contextual guidance. It does not explicitly name sibling alternatives or state when not to use it, but the 'for one item' phrasing implies the boundary versus list-style tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description need not re-state safety. The description adds value by naming the computed metrics (LTV, CAC, ratio) and the optional segmentation, which gives the agent a sense of the output scope. However, it does not disclose behavior like timezone handling (already in schema) or error conditions. The addition of metric names is useful, but not extensive, so a 3 is appropriate.

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 one sentence, front-loaded with the core purpose and then optional segmentation. Every word is necessary; no filler. It is appropriately sized for the tool's complexity.

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 there is an output schema (visible to the agent, though not fully in the prompt) and rich annotations, the description sufficiently covers the tool's purpose and key fields. The only missing element is explicit guidance on when to use it versus other LTV-related siblings, but given the tool's simplicity and the output schema, it is mostly complete for an agent 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% for all three parameters, with detailed descriptions of each parameter in the schema. The description mentions 'segmented by country' which maps to the segment_by enum but does not add syntax or type details beyond what the schema provides. The description does clarify that only 'country' is available in this release (though the schema is more detailed, it includes other enum values), but the schema description already covers this nuance adequately. Since the schema handles semantics, the description adds minimal 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?

The description clearly states the tool returns customer lifetime value summary with optional segmentation by country and includes the key metrics (average LTV, CAC, LTV:CAC ratio). It is a specific verb-resource pair ('Get LTV summary') that distinguishes it from sibling analytics tools. The description is concise and action-oriented, leaving no ambiguity about what the tool does.

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

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

The description implies usage for retrieving LTV summaries, but it does not explicitly state when to use this tool versus siblings like get_cac_payback or get_cohort_analysis. There is no mention of prerequisites (e.g., attribution enabled) or when NOT to use it. However, the description does mention the optional segmentation, giving some context. The lack of explicit guidance for alternative tools prevents a higher score.

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

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context by noting results are ranked by variant and bundle contribution margin and that the tool uses the same service as the dashboard. This is useful but not extensive; it does not describe output structure or pagination, though an output schema exists.

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 a single 30-word sentence with no filler and the key purpose is front-loaded. The phrase 'using the same service as the dashboard' is somewhat vague but not wasted; it gives a provenance signal. It is appropriately concise and readable.

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

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

Given the rich input schema (100% parameter coverage), strong annotations, and presence of an output schema, the description covers what is needed for basic invocation. It could improve by explicitly naming sibling alternatives or clarifying the product-list output shape, but for a read-only, well-schematized tool it is substantially complete.

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

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

Schema description coverage is 100%, and every parameter already has a meaningful description covering defaults, formats, clamping behavior, and timezone resolution. The tool description adds no additional parameter-level meaning, so the baseline 3 is appropriate: the schema does the heavy lifting and the description does not need to compensate.

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 action ('Get'), a resource ('Markets country drilldown'), and a ranking criterion ('variant and bundle contribution margin'), which makes the core purpose clear. It does not explicitly distinguish itself from closely related siblings like get_markets or get_top_products, but the 'country drilldown' and product-level focus separate it enough for a 4.

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

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

The description implies when to use the tool: when a country-level product drilldown ranked by contribution margin is needed. However, it gives no explicit guidance about when not to use it or which alternative sibling tools to prefer, such as get_markets for country aggregates or get_top_products for global rankings. The usage context is clear but the routing guidance is only implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is established. The description adds useful behavioral context by specifying that results include real geo ad spend, blended fallback spend, revenue, net profit, margins, ROAS, POAS, CAC, and spend-without-orders markets.

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 a single, front-loaded sentence that opens with the action and resource and then enumerates the included metrics. It is concise, information-dense, and contains 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?

Given the rich parameter schema, output schema, and annotations, the description covers the essential intent and output scope. Nothing critical for selecting or invoking the tool correctly is missing.

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

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

Schema description coverage is 100%, with detailed parameter descriptions for start_date, end_date, limit, sort_by, country_codes, and include_spend_without_orders. The tool description does not add parameter-level meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Get the Markets dashboard table for a date range'. It lists the exact metrics included, making the tool's purpose unmistakable and distinguishing it from related market/product tools like get_market_products.

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

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

The description clearly states the tool returns the Markets dashboard table for a date range, so an agent knows when this tool is appropriate. It does not explicitly name alternatives or exclusions, but the context is clear enough for selection among the many sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-mutating operation. The description adds two behavioral specifics: it filters for 'active' agreements and includes the 'impact on current period P&L'. These are useful, but the description does not disclose edge cases (e.g., behavior when no active agreements exist, or whether the P&L impact is a calculated figure). Given the annotations cover the safety profile, the description's added value is moderate, warranting a 3.

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 a single, tightly worded sentence that front-loads the action ('Get') and lists the key outputs (agreements, repayment schedule, P&L impact). Every word contributes to the meaning, with no redundancy or filler. It is appropriately concise and well-structured for a simple read-only tool.

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

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

Given the tool has no parameters and an output schema exists (which will define the return fields), the description only needs to convey the high-level content, which it does: it specifies the three main components (active agreements, repayment schedule, and current-period P&L impact). For a no-argument read-only tool, this is fully sufficient for an agent to call it correctly and interpret the response shape via the schema.

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

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

The tool has zero parameters, and the schema is empty with 100% coverage. According to the rubric, a 0-parameter tool receives a baseline score of 4. The description does not need to elaborate on parameters since there are none, and it correctly omits any parameter-related discussion. No additional semantic value is required or possible here.

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

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

The description clearly states the tool's purpose: it retrieves active revenue-based funding (MCA) agreements, repayment schedule, and their impact on the current period P&L. This is a specific verb-resource pairing (get + MCA status) that distinguishes it from sibling tools like get_bank_balance or get_pnl_summary, which address different financial aspects. The term 'MCA' is defined, removing ambiguity.

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

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

The description provides clear context for when to use the tool—whenever an agent needs MCA agreement details, repayment schedules, or their effect on P&L. It does not explicitly name alternative tools or state when not to use it, but the specificity of the resource (MCA) makes the usage context unambiguous. A small exclusion note would have made it perfect, but it is not necessary for this straightforward read.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds modest context beyond those annotations by specifying that this is a snapshot of configured KPIs and listing the computed fields returned, but it reveals no further behavioral traits such as freshness or aggregation behavior.

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

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

A single 19-word sentence that front-loads the verb and resource, then compresses the deliverable into four concrete data fields. Zero filler words; every element 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 low-complexity, read-only tool with one fully described optional parameter, a rich annotation set, and an output schema, the description covers the essential payload (target, actual, delta, trend). The only gap is usage/alternative context, which is minor given how self-contained and unambiguous this tool is.

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%: the single optional 'period' parameter is fully documented in the schema with its enum values, their exact date windows, and the 'month' default when omitted. The description adds nothing about parameters, but with this coverage the baseline 3 is appropriate — the schema carries the burden.

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

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

States a specific verb ('Get'), an exact resource ('status of all configured North Star KPIs'), and enumerates the returned fields (target, actual, delta, trend direction). The 'current status' framing plus the field list makes it distinct from every sibling, none of which target North Star KPIs.

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

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

The description provides no when-to-use guidance, no exclusions, and no alternative tools. Unlike get_calls, it never names a sibling to prefer for other metric questions (e.g., get_anomalies, get_pnl_summary), so an agent must infer the appropriate context from the name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the comparison feature and the breakdown categories, but does not disclose additional behaviors like data freshness, handling of missing periods, or whether the summary is tenant-scoped (though that's implied). It does not contradict annotations, so a 3 is appropriate.

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 a single, well-structured sentence that front-loads the core purpose and then mentions the optional comparison. No wasted words; it is concise and immediately informative.

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

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

Given the tool has an output schema (not shown but present), the description need not detail return values. The description covers the main behavior, optional comparison, and the breakdown components. Minor gaps like timezone resolution are already in parameter descriptions, and the read-only nature is in annotations. It is adequately complete for a read-only summary tool.

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

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

Schema description coverage is 100%, so the parameters (start_date, end_date, compare_to) are already well-documented with types, formats, and meaning. The description reinforces the date-range and comparison concepts but adds no new parameter syntax or constraints beyond what the schema provides. Baseline 3 applies when schema carries the burden.

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

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

The description clearly states it retrieves a profit and loss summary over a date range, broken down by specific financial components, and optionally compares to previous periods. It names the resource (P&L summary), the action (get), and the scope (date range), which distinguishes it from siblings like get_revenue_breakdown or get_expenses_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?

The description implies its use case (getting a P&L summary) but does not explicitly state when to prefer this over alternatives like get_combined_pnl or get_date_range_summary. No exclusions or alternative tools are mentioned, so the agent must infer when this is the right choice from the tool name and description alone.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, so the description does not need to repeat safety info. It adds value by clarifying the source of data ('from the analytics snapshots'), which hints at potential staleness and distinguishes it from real-time sources. This is useful context beyond the annotations.

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

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

The description is a single, well-structured sentence that leads with the core purpose, then enumerates key data points, and ends with the data source. Every clause adds information; no fluff.

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

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

Given the tool's moderate complexity and the presence of an output schema, most return details are covered. The description adequately sets expectations for what fields are returned (catalogue price, variant pricing, COGS, 90-day trend) and the parameter semantics are clear. A slight gap is not explaining that the data may be based on snapshots, but that is hinted.

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?

While the schema already covers the parameter at 100% coverage, the description adds critical disambiguation: the product_id must be the internal MerchantFlow id, not the commerce platform's. This is exactly the kind of semantic context that prevents misuse.

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 ('Get') and a precise resource ('detailed profitability for a specific product'), then lists the exact data returned: catalogue price, variant-level pricing, COGS, and 90-day trend. This clearly distinguishes it from siblings like get_customer_detail or get_top_products, which target different entities.

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

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

The description implies when to use it: when needing product-level profitability details, as opposed to aggregate or trend views. It doesn't explicitly state when not to use it or name alternatives, but the specificity is strong enough for an agent to infer the right context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the behavioral detail of a 'chronological feed', which is useful, but does not disclose other potential behaviors like rate limits or response size constraints.

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 a single, concise sentence that leads with the action and resource, and it packs the key detail (activity types) efficiently. No filler or redundant 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?

Given that an output schema exists and annotations cover safety, the description covers the core purpose. It could mention the default time window (24 hours) explicitly, but that is already in the schema parameter description. Overall, it is sufficient for an agent to decide to call it.

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

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

Schema description coverage is 100%, with both parameters having explicit descriptions. The tool description reiterates the activity type examples from the schema but adds no new semantic meaning beyond what the schema already provides.

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 clear verb ('Get') and resource ('recent tenant activity') and lists specific activity types (syncs, large orders, integration events). It is distinct from sibling tools by naming these feed categories, though it does not explicitly contrast with any sibling.

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

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

No guidance is provided on when to use this tool versus alternatives like get_anomalies or get_date_range_summary. The description does not indicate selection criteria or when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds minimal behavioral context (e.g., date-range scoping) but does not describe return format or pagination; the output schema exists but is not referenced. This is adequate given 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?

The description is a single, efficient sentence with no redundant words. It front-loads the core action and scope, achieving maximum conciseness.

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

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

For a read-only tool with an output schema and detailed parameter schema, the description is minimal but not wholly inadequate. It omits usage guidance and fails to correct the misleading group_by schema description. Given the complexity and the presence of many sibling tools, a bit more context would improve 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%, with each parameter (start_date, end_date, group_by) having its own description. The tool description adds no parameter-level detail. However, the group_by schema description is inconsistent—it describes values like 'source' and 'channel' that are not in the enum (which only allows 'country')—and the tool description does not clarify this. Baseline of 3 applies since schema does the heavy lifting.

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

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

The description 'Get revenue broken down by country over a date range' clearly states the verb, resource, and scope. It is specific enough to distinguish from many sibling tools that focus on other metrics, though it doesn't explicitly contrast with revenue-related siblings like get_pnl_summary.

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?

No guidance is provided on when to use this tool versus alternatives. The sibling list includes numerous get_* tools, but the description offers no context on selection criteria, exclusions, or prerequisites.

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, so safety is covered. The description adds the semantic context that the result is the store set for combined figures, which is useful but not a behavioral trait like side effects or auth requirements. No contradictions with annotations.

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

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

The description is two sentences with no filler. The main action is front-loaded, followed by the field list and a single clarifying statement about its role in combined figures. 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?

For a simple list tool with no parameters, an output schema present, and annotations covering safety, the description is complete. It tells the agent exactly what the tool returns and the purpose it serves. No missing information is needed 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 has zero parameters, so the schema fully covers them (100% coverage by trivially having none). The description does not need to add parameter information. It does mention output fields, but that is not parameter semantics; the baseline of 3 applies when schema coverage is high and no parameter info is added.

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 ('List'), a clear resource ('the stores linked to this account'), and enumerates the fields returned (platform, currency, timezone, connection state, last sync time). It also clarifies the purpose by defining this as the store set for combined figures, distinguishing it from other get_* tools like get_markets or get_integration_status.

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

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

The description provides context that this tool defines the store set available for combined figures, which implies when to use it (when you need the authoritative list of stores for aggregated metrics). However, it does not explicitly contrast with alternatives or state when not to use it, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral detail by explaining that tax figures combine platform-reported order tax with computed manual TaxRule entries where the platform reported none or a fixed-amount rule applies. This clarifies the underlying calculation behavior beyond the annotations.

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

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

The description is three sentences with no filler. The primary output is front-loaded, the second sentence explains a nuanced data-combination behavior, and the third sentence gives a useful dashboard comparison. 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?

Given the tool has one optional parameter, a rich output schema, and safety annotations, the description is largely complete: it states the result components, the data sources, and the calculation nuance. The only gap is the absence of explicit alternative-tool routing, but that is already accounted for under usage guidelines.

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% for the single 'days' parameter, including its bounds and default value. The description only mentions a 'trailing N-day window' and does not add extra parameter-level semantics, so it neither compensates for missing schema documentation nor adds meaningful value beyond it.

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

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

The description opens with a specific verb and resource: 'Get period tax totals and the blended effective tax rate over a trailing N-day window, plus a per-country split.' This clearly distinguishes it from sibling reporting tools by naming tax-specific outputs and the country breakdown, so an agent can recognize its purpose without ambiguity.

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

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

The description implies the tool is for tax-period summaries by noting it 'Mirrors the dashboard tax settings page tiles,' but it does not explicitly state when to use this tool over alternatives or when not to use it. No sibling alternative is named, so the usage guidance is only implied rather than explicit.

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

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

The read-only, idempotent, and non-destructive traits are already supplied by annotations, so the description only needs to add extra behavioral context. It does so with the clause 'using the same order-based product profit math as the dashboard,' which clarifies the exact profit methodology and promises dashboard-consistent figures. There is no contradiction with 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?

The description is a single sentence with the action and result front-loaded: 'Get the top N products ranked...'. The final clause about dashboard math is the only elaboration and it earns its place by specifying methodology. There is no filler, repetition, or restatement of the title.

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

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

For a read-only ranked-list tool with a fully documented input schema, an output schema, and annotations covering safety, the description covers the remaining essentials: what is returned, the ranking dimensions, and the date range. Operational details such as the 50-product cap, timezone resolution, and 'highest first' ordering live in the schema, so nothing critical 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%, with start_date, end_date, limit, and rank_by all individually documented, including format, bounds, defaults, and enum values. The description only restates those concepts at a high level ('ranked by revenue, profit, margin, or units sold', 'over a date range') and does not add new parameter-level meaning. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Get the top N products ranked by revenue, profit, margin, or units sold over a date range.' The 'top N' phrasing separates it from the sibling get_bottom_products, and the ranking-metric list makes clear this is a ranked list rather than a detail lookup like get_product_detail.

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

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

The description implies usage when a ranked list is wanted, but it never states when to prefer this tool over alternatives such as get_bottom_products or get_product_detail, nor does it give any when-not-to-use conditions. An agent has to infer applicability from the name and sibling list rather than from explicit 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context by specifying the exact categories of connection capabilities reported, such as current rate-limit headroom and cross-store availability, which goes beyond the generic title and 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?

A single, front-loaded sentence efficiently lists the tool's output categories without filler or redundancy. Every phrase adds information, making the description easy to parse and acting on.

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

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

With no parameters, an output schema, and a read-only/idempotent annotation profile, the description provides all necessary context for an agent to invoke the tool correctly. The enumerated result categories fully convey what the tool will report, so nothing critical 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 input schema has zero parameters and 100% schema description coverage, so there is nothing for the description to clarify. The baseline for a no-parameter tool is 4, and the description appropriately focuses on what the tool returns rather than inputs.

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 uses a specific verb ('Report') and precisely identifies the resource: this connection's plan tier, available history, cross-store availability, rate-limit headroom, and data limits. It clearly differentiates this introspection tool from the many data-oriented sibling tools by enumerating exactly what capability information is returned.

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

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

The description implies a clear use case—checking connection capabilities like rate-limit headroom and data limits—but it does not explicitly state when to prefer this tool over siblings such as get_integration_status or get_mca_status. No exclusions or alternative conditions are given, so usage guidance 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 readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds valuable behavioral context: sorting by newest effective date, enrichment with product/variant, pagination, and filtering options. These are not available in the schema and help an agent understand the tool's behavior beyond safety.

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

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

The description is two sentences with zero waste. The core purpose and scope are front-loaded, followed by a compact summary of pagination and filters. Every clause earns its place, making it highly efficient.

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

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

Given the output schema exists, the description need not explain return values. It covers the listing scope, ordering, enrichment, pagination, and filter options. It does not mention timezone resolution for date filters, but the schema already handles that. Overall, it is complete for a list tool of this complexity.

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 every parameter already has a detailed description. The tool description summarizes pagination and filtering but adds no new semantics beyond a concise overview. Since the schema carries the full load, the description meets the baseline of 3 without adding extra depth.

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 clear verb ('List') and resource ('cost-of-goods-sold entries') with explicit scope ('for all items and variants') and a specific ordering ('newest effective date first'). It also mentions enrichment with product and variant, which distinguishes it from single-item tools like get_item_cogs. The purpose is unambiguous and distinguishable from siblings.

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

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

The description clearly indicates this tool lists all COGS entries, implying it is for broad queries rather than single-item lookups. However, it does not explicitly name alternatives (e.g., get_item_cogs) or state when not to use it. The context is implied but not made explicit, so an agent might need to infer the boundary.

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 annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses important behavioral quirks: customer name and email are partially redacted, the date range only selects which customers appear rather than clamping their lifetime totals, and each id points to a detail record with up to 200 recent orders. This is exactly the kind of non-obvious behavior an agent needs to know.

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 with no filler. The core definition is front-loaded, followed by the most important semantic caveat, then response-level redaction and id behavior. Every sentence earns its place without repeating schema defaults.

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

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

The tool has an output schema, so return-value structure does not need to be restated. The description supplies the missing context: metric definition, dashboard parity, date-filter semantics, redaction, and what the returned ids point to. Nothing critical is missing for an agent to call this correctly.

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

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

The input schema already documents all six parameters with 100% coverage, so the baseline is 3. The description adds a valuable clarification that start_date/end_date filter by first-order date and do NOT clamp lifetime totals, which prevents an easy misuse not fully spelled out in the schema.

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

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

The description uses a specific verb and resource: 'List customers ranked by lifetime value' and precisely defines the metric ('net profit after allocated overhead, summed across each customer's full order history'). It also distinguishes this tool by tying it to the dashboard Customers page and noting that each returned id maps to a customer detail record, which helps separate it from get_customer_detail and get_ltv_summary.

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

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

The description gives clear context for when to use it: it mirrors the dashboard Customers page and returns an LTV-ranked customer list. It does not explicitly name alternatives or exclusion conditions, but the dashboard-source statement and the precise filter semantics provide enough situational 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the taxonomy of what the listing contains and that ids are generation-ready, which is consistent with the closed-world annotation. It adds no further behavioral detail (ordering, pagination, or how items are mixed when type is omitted), but with strong annotations plus an output schema present, this is an acceptable level of disclosure.

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

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

Two sentences totaling roughly 30 words, with the core action ('List every report available to this store') front-loaded in the first sentence and the output's purpose in the second. There is no repetition of the title and no filler; 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-required-parameter listing tool with full schema coverage, comprehensive annotations, and an output schema present, the description is nearly complete. The only meaningful gap is the absence of an explicit pointer to the consuming sibling (generate_report) to close the workflow loop, which the phrase 'available for generation' partially mitigates.

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

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

Schema description coverage is 100%: both the type enum (with semantics for each value) and include_archived (with default and behavior) are fully documented in the schema, setting the baseline at 3. The description reinforces the enum taxonomy (template=catalogue, custom=saved) and explains what returned identifiers mean, adding modest value beyond the schema without contradicting it.

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

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

The description uses a specific verb+resource pair ('List every report available to this store') and enumerates the three output categories (saved template reports, custom reports, built-in template catalogue), which distinguishes it from sibling list_* tools like list_customers, list_cogs, and list_capabilities by resource type. The final sentence ties returned ids to 'generation,' implicitly contrasting with generate_report. It stops short of 5 because of a minor vocabulary overlap between 'saved template reports' and the 'template' type enum.

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

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

The description implies a list-then-generate workflow ('Each returned report id or template key identifies a report available for generation') and clarifies the tool's scope (reports, not stores/customers/cogs). However, it never names an alternative tool (e.g., generate_report) nor states when NOT to use this tool, leaving routing decisions to agent inference rather than explicit 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is known. The description adds the specific return fields (line items, margin, fulfillment state, refund history), which is valuable context beyond the annotations. It does not discuss auth, rate limits, or error behavior, but for a read-only lookup that is acceptable.

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 a single sentence that front-loads the action and resource, then lists the return contents. Every word earns its place; there is no fluff or redundancy.

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

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

With an output schema present and a single well-documented parameter, the description fully covers what an agent needs to call the tool correctly. It states the purpose and the return fields, and the schema handles parameter details. No significant information 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 parameter description in the schema already explains the format (with or without leading '#'). The tool description does not add any parameter-specific information beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific verb ('look up'), resource ('a single order by number'), and lists the returned data (line items, margin, fulfillment state, refund history). This distinguishes it from search_orders or report tools; an agent can immediately tell it is for retrieving a specific order.

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

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

The description implies usage when you have a specific order number and need its details, but it does not explicitly name alternatives or exclusion conditions. It provides clear context ('single order') but lacks an explicit when-not-to-use statement, 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 read-only, idempotent, and non-destructive behavior. The description adds valuable context about the output: order counts, net revenue, charged vs. actual shipping cost, and an explicit coverage percentage for the cost side—details not inferable from the annotations or schema alone.

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 three tightly written sentences with no filler. It front-loads the core operation, then supplies a clarifying example, then describes the return payload. 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?

Given the 9-parameter complexity, the description covers the essential aspects: the unique basket-filtering behavior, the grouping dimensions, and the non-obvious dual shipping figure semantics. The full input schema, annotations, and output schema handle the remaining details, so nothing critical 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 every parameter is documented. The description enriches these meanings by mapping the filter concept (basket products and quantities) to the relevant parameters and using the example 'orders containing two chairs' to clarify exact_quantity and min_quantity usage.

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

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

The description clearly states the tool's specific function: analyzing orders filtered by basket contents and grouping by region, channel, or month. It also distinguishes itself from pre-computed dashboard context and provides a concrete example query, making its purpose unmistakable even among many sibling analytics tools.

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

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

The description explains when this tool is the right choice ('Answers questions the pre-computed dashboard context cannot') and gives a concrete example. However, it does not explicitly name alternative tools or state when not to use it, so it leaves some routing judgment to the agent.

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, so the description only needs to add context. It adds that matches include a similarity score and that the tool supports disambiguation, which goes beyond the annotations without contradicting them.

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 concise, front-loaded sentences: the first states the core resolve-to-IDs behavior with examples, and the second gives the key output trait and use case. There is no filler, repetition, or extraneous detail.

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 simple two-parameter, read-only resolver with a full input schema and output schema, the description covers the necessary context: accepted input types, return concept (product IDs with similarity scores), and the intended analytical use case. Nothing essential 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?

With 100% schema description coverage, the baseline is 3. The description adds value by giving concrete example query values and clarifying that query can be a product name, category word, or SKU, which helps the agent formulate valid calls. It does not add anything about limit beyond the schema.

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

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

The description opens with a specific action ('Resolve') and a concrete resource ('product name, category word or SKU... to concrete product IDs'), backed by concrete examples like 'chairs', 'oak desk', and 'CHR-01'. It clearly distinguishes this tool from the many sibling report/query tools by focusing on catalog ID resolution rather than reporting or analytics.

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

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

It gives clear context: use this when natural-language product references, category words, or SKUs need to be resolved to catalog IDs for product-level basket analysis. It does not explicitly name sibling alternatives or state when not to use it, so it stops short of full when/when-not routing.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's 'Read-only - does not send messages' partially repeats this. However, the explicit statement about not sending messages adds a specific behavioral guarantee not fully captured by the read-only hint alone. The description does not contradict annotations, and it provides a small additional detail about side-effect-free operation.

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

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

The description is extremely concise: two short sentences that state the purpose and the read-only nature. There is no redundancy or filler, and the key information is front-loaded. Every word earns its place, making it an exemplar of minimal but informative writing.

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

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

Given the simple single-parameter interface, the presence of an output schema, and annotations covering safety, the description covers the essential facts. It does not explain how results are ordered or paginated, but those may be documented in the output schema. The only notable gap is the lack of differentiation from similar tools, which is more of a usage-guideline issue and already penalized there. Overall, the description is sufficient for a straightforward read-only operation.

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 input schema has 100% description coverage for the single 'days' parameter, including a clear range and default. The tool description adds no additional semantics about the parameter, so it relies entirely on the schema. This meets the baseline for high schema coverage, though it does not enhance the parameter understanding beyond what is already available.

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 that the tool identifies recent abandoned checkouts with recoverable value, making the core purpose clear. However, it lacks an explicit verb like 'list' or 'retrieve', and it does not distinguish itself from the closely named sibling 'run_win_back_candidates', which could cause confusion. The title 'Abandoned Cart Candidates' reinforces the intent but does not fully differentiate.

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

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

There is no guidance on when to use this tool versus alternatives such as 'run_win_back_candidates' or 'run_repeat_purchase_rate'. The description only states what it does, not when it should be selected over other similar tools. No exclusions or preferred contexts are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it returns a valuation range with sensitivity analysis, which is useful output context. However, it does not disclose any additional behavioral traits such as data dependencies or performance characteristics, but this is minor given the read-only nature.

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 a single sentence that front-loads the action and then provides the key inputs and output. It is concise but packs essential information without unnecessary fluff.

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

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

For a tool with one optional parameter and an output schema present, the description is sufficient. It states the inputs (P&L, growth, margin, MER, risk) and the output (valuation range with sensitivity analysis). No prerequisites or error conditions are mentioned, but given its simplicity and read-only nature, this is not a critical gap.

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

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

The schema description for lookback_months is very detailed, explaining the mode switch (6 vs 12 months) and matching the dashboard. Since schema coverage is 100% and the parameter is well-documented, the description does not need to add more. The baseline of 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states the tool runs an SDE-multiple business valuation based on specific factors (P&L, growth, margin, MER, risk) and returns a valuation range with sensitivity analysis. It uses a specific verb (run) and resource (business valuation), and is distinct from siblings like run_inventory_valuation.

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

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

The description provides clear context on what the tool does and the basis of the valuation, but does not explicitly mention when to use it over alternatives or any exclusions. Given the tool is the only business valuation tool in the sibling list, the lack of explicit alternatives is acceptable.

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