ViralSweep MCP by usefulapi

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's job is to add context — and it does: it discloses that pagination happens locally over a bounded vendor response rather than via vendor-native paging. That warns the agent results may be capped or incomplete, which is genuine value beyond the annotations, though it does not say what happens when offset exceeds the vendor bound.

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

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

Two short sentences with no filler, and the core purpose is front-loaded. The second sentence is slightly hedged ("no vendor-native pagination is claimed") but it carries real information about pagination semantics.

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, two-parameter list tool this is close to adequate, and the pagination caveat is the most important thing an agent needs. However, with no output schema the description never indicates what a brand record contains or how to tell whether more results exist, leaving the agent to discover the shape at call time.

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

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

Schema description coverage is 0%, but the schema itself carries types, defaults and min/max bounds for both parameters. The description adds the missing semantic layer: offset/limit are applied locally against a bounded response rather than forwarded to the vendor, which changes how an agent should interpret a full page of results.

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?

"Read account brands" states a specific verb and resource, and the resource (brands) is inherently distinct from the sibling tools (entries, promotions, winners). It is clear what the tool returns, though the description does not explicitly contrast itself with those 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?

There is no explicit guidance on when to use this tool versus the sibling list tools, nor on prerequisites (account scoping, credentials). The only implied usage is that this is the brands listing endpoint, which an agent could already infer from the name.

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

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

Annotations already declare readOnly/idempotent/non-destructive and open-world, so the safety profile is covered. The description adds real value beyond them: results are paginated per 'vendor page' and login links plus arbitrary form fields are deliberately excluded, which warns the agent about missing fields.

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

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

Two tight sentences with no waste; the output content is front-loaded and the search/exclusion caveats follow in the right order.

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 usefully previews the returned fields (entrants, emails, entry/referral counts) and warns about exclusions. It is only short of page-size semantics and how to obtain the promotion_id, which are minor given the schema.

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

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

Schema coverage is 0%, so the description must carry the load; it explains page ('one vendor page') and query (email-address search), but says nothing about 'count' (page size, max 100) or the required promotion_id beyond its name. Partial compensation for a 4-parameter tool.

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

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

States a specific verb and resource: reading a page of promotion entrants with emails and entry/referral counts. The resource (entries) is distinct from siblings (brands, promotions, winners), so an agent can discriminate, though no sibling is named explicitly.

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

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

Implies usage for pulling entrant data and notes the optional email search, but gives no explicit when-to-use vs. the other viralsweep_list_* tools and no prerequisites such as needing a valid promotion_id from viralsweep_list_promotions.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds one useful behavioral fact — pagination happens locally over a bounded vendor response — but says nothing about rate limits, filtering semantics, or what the vendor cap means in practice.

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

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

Two tight sentences with the scope statement front-loaded and no filler. The phrase 'bounded vendor response locally' is slightly jargon-heavy but earns its place by disclosing pagination behavior.

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

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

For a read-only list tool with no output schema and zero param documentation, the definition is serviceable but thin: an agent still cannot tell the return shape, page-size behavior, or how the archived flag combines with active_only.

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

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

Schema coverage is 0%, so the description must carry the load. It gestures at offset/limit and the active/archived flags, covering four of five parameters conceptually, but never explains brand_id as the required key, the limit ceiling of 100, or how active_only and include_archived interact.

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 ('Read') and resource ('promotions for a brand') plus its scope options (active or archived). Siblings operate on brands, entries, and winners, so the resource noun alone distinguishes it, though it never explicitly contrasts with them.

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?

'Optionally active or archived' hints at when the filter flags apply, but there is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives among the sibling list 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: offset/limit page a bounded response locally, and private login and prize redemption codes are excluded from results. That exclusion detail is the kind of context annotations cannot convey.

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

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

Three tight sentences, front-loaded with what is returned, then the non-selection guarantee, then paging/exclusion behavior. Every sentence contributes distinct information with no filler.

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

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

With no output schema, the description usefully discloses what is returned (winners and prize titles) and what is omitted (private login and redemption codes). It could go further on response shape or pagination bounds, but it is sufficient 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 description coverage is 0%, so the description must carry the burden, and it does: it maps 'Unix timestamps' to begin_ts/end_ts, 'offset/limit page' to those two params, and 'a promotion's winners' implies promotion_id. It does not state the limit ceiling (100) or default (50), leaving a small gap.

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

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

States a specific verb and resource ('Read a promotion's winners and prize titles') that clearly distinguishes it from sibling list tools covering brands, entries, and promotions. The additional clause 'Reads existing winners without selecting new ones' removes any ambiguity about whether this triggers a draw.

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 usage context: use it to read existing winners, optionally filtered by Unix timestamps, and it explicitly says it does not select new winners. It does not name an alternative sibling tool or state a when-not condition by name, 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.