get_discount_frequency_and_depthHow often and how deep each brand discounts: promo days vs observed days, average and max discount %, and promo types, over a window (7-365 days, default 30).
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| domains | No | Brand domains from your RivalSweeper account, e.g. ["gymshark.com"]. Omit for all your tracked brands. |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds meaningful content beyond that by specifying exactly which metrics are computed (promo days vs observed days, average and max discount %, promo types), which effectively describes the output in the absence of an 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 that leads with what the tool does and folds the window parameter in at the end. No filler and nothing redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does list the computed metrics and per-brand grouping. It is largely sufficient for a 2-param read tool, though it omits any note on the domain scoping that the schema handles.
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 50%: domains is documented in the schema, but days is bare. The description compensates by giving the window range (7-365 days) and the default (30), adding real meaning to the otherwise undocumented days parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (get) and resource (discount frequency and depth) and enumerates the metrics produced: promo days vs observed days, average and max discount %, promo types. It is clear what the tool computes, but it never distinguishes itself from related siblings like get_active_promotions_and_coupons or get_most_discounted_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 contains no when-to-use guidance, no prerequisites, and no mention of alternatives. The window/default note is parameter information, not usage context, so the agent must infer when this brand-level discount posture metric is preferable to the sibling promo and discount tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.