Ecommerce Leads

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

Goes well beyond the annotations by disclosing the credit cost model (1 credit per *new* domain), the idempotent-ish merge behavior, the insufficient-credit failure mode where nothing is added, and the plan gating. The destructiveHint=true is explained in practice as irreversible credit spend, so nothing conflicts.

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

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

Front-loaded with purpose, then cost, then the required confirmation step, then the failure mode — a sensible order for an agent. Slightly repetitive in phrasing the credit cost twice ('1 credit per domain that is new' / '1 credit per store') and the all-caps emphasis is heavy, but no sentence is truly wasted.

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

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

For a two-parameter mutation with no output schema, the description covers the things that actually matter: cost consequences, required user confirmation, plan restriction, and what the caller sees on failure. Nothing an agent needs to invoke this safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by clarifying that cost applies only to domains new to the list, and the confirmation message needs the total domain count. It does not restate the 50-item cap or listId sourcing, but those are already in the schema.

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

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

States a specific verb and resource ('Add domains to a watchlist') and immediately disambiguates the mutation's nature with '(merge, nothing is removed)', which separates it from createWatchlist and removeFromWatchlist without needing their schemas.

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

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

Gives explicit preconditions and a required workflow: tell the user the cost and domain count, get confirmation, never call without it, and paid plans only. These are hard when/when-not rules rather than implied 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 establish this is a non-readonly, non-destructive, closed-world write. The description adds behavior those hints cannot convey: a plan-level entitlement gate and a 10-list quota that counts the blacklist, both of which are essential failure-mode context. It stops short of saying what the response contains or whether names must be unique.

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 with zero filler; the core action leads and the constraints follow. Every clause (empty, 10-list cap, paid plans) carries distinct information an agent needs.

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

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

For a one-parameter creation tool with no output schema and clear annotations, the definition covers the action, the entitlement gate, and the quota. The only real gap is that an agent cannot tell from the description whether a new list identifier is returned for use with addToWatchlist.

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 a single required "name" field already documented as the list name with a 100-char cap, so baseline is 3. The description adds no meaning about naming constraints, uniqueness, or reserved names beyond what the schema supplies.

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 ("Create an empty watchlist") and the word "empty" usefully separates it from addToWatchlist, which populates an existing list. It does not explicitly name deleteWatchlist/renameWatchlist/getWatchlist as the non-creating alternatives, but the create-vs-modify split is still inferable.

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

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

Gives a real precondition ("Paid plans only") and a hard cap ("at most 10 lists, including the blacklist"), which tell the agent when the call will fail. It never states when to prefer this over the other list-management siblings or what to do once the cap is hit, so usage is implied rather than directed.

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 flag destructiveHint=true, but the description adds value beyond them: irreversibility ('You cannot undo this'), the downstream effects on matching stores, listSignalSets, and dashboard tabs, the paid-plan gating, and the required human confirmation flow. This is exactly the extra context an agent needs for a destructive 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?

Five short sentences, front-loaded with the action and consequence, then irreversibility, then the safety protocol, then the plan gate. No filler and nothing repeated from the schema.

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

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

For a single-parameter destructive tool with annotations and no output schema, the description covers consequences, irreversibility, confirmation protocol, and plan restrictions — everything needed to call it safely and correctly.

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

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

Schema description coverage is 100% and setId already documents 'The set id from listSignalSets.' The description adds no additional syntax or edge-case meaning for setId, so it sits at the baseline for a fully documented single 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?

The description opens with a specific verb and resource ('Delete one of your signal sets'), then immediately states the consequence ('stops matching stores and disappears from listSignalSets and from the dashboard tabs'), which distinguishes it from sibling reads like getSignalSet and listSignalSets.

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

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

It gives concrete preconditions: 'Ask the user to confirm before you call it', 'Say the name of the set in your question', and 'Paid plans only'. It also points to listSignalSets for the id. It does not explicitly frame when-not-to-use (e.g., to stop matching temporarily, use a different mechanism), so it is clear context but not full alternative routing.

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

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

Beyond the destructive annotation, it discloses the deletion's full scope by stating that all domains in the watchlist are included. It also adds the confirmation requirement, paid-plan restriction, and undeletable blacklist exception.

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 front-loads the operation and its destructive scope, then presents the exception, confirmation requirement, and plan restriction in short sentences. Every sentence supplies useful invocation information without unnecessary wording.

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 one-parameter deletion tool, the description and schema together provide the operation, cascade scope, identifier source, eligibility restriction, exception, and confirmation requirement. The lack of an output schema or return-value explanation is not a meaningful obstacle to 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%, and the listId schema already explains that the identifier comes from listWatchlists. The description adds no further parameter syntax, selection, or validation details, so the baseline score 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 and resource: it deletes an entire watchlist together with all its domains. This also distinguishes it from removeFromWatchlist, which implies removing individual entries rather than deleting the list.

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

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

It provides explicit constraints and prerequisites: the blacklist cannot be deleted, user confirmation is required before invocation, and the tool is limited to paid plans. These details give the agent clear guidance on when not to call it and what to establish first.

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 thin annotations, the description discloses the important behaviors: un-revealed stores are silently excluded, output is capped at 200 data rows plus a header, truncation is signaled in the result, and access is plan-gated. It doesn't clarify whether the call consumes credits or whether the export is a side-effect-free read, which matters given readOnlyHint=false on what reads like a pure export.

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?

Five short sentences, purpose front-loaded, then exclusion rule, size limit, workaround, and access gate. No sentence is filler and each adds a distinct operational fact.

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

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

For a two-parameter tool with a nested selection object and no output schema, the description does the necessary work: it explains the return shape (header row + rows, truncation note) and the 200-row ceiling. It stops short of explaining how the export relates to prior reveal actions or credits, which is the one remaining gap.

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

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

Schema description coverage is 100% and the nested selection/filters/operators are all documented inline, so the schema carries the parameter burden. The description adds only "narrow the selection" as a hint, with no added meaning about ids vs tab semantics. Baseline 3 applies.

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

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

The first sentence names a specific verb and resource ("Export revealed stores as CSV text") and immediately establishes scope (revealed only). It is clearly distinguishable from siblings like searchStores or revealStores, though it never names an alternative tool path.

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 supplies two useful usage signals: stores not revealed are skipped, and for larger exports you should narrow the selection or use the dashboard instead. The "Paid plans only" line is a real precondition. What's missing is any explicit routing versus sibling tools (e.g. why export here rather than paging through searchStores), so usage is implied rather than stated.

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

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

Annotations already cover readOnlyHint and destructiveHint, but the description adds non-obvious guarantees: no credits are charged and no data is exposed by the call. That is genuine behavioral context an agent cannot derive from the annotations, since a 'cost preview' could plausibly reserve or consume credits.

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: purpose first, the no-side-effect guarantee second, the return shape third. No filler, no repetition, and the most decision-relevant information is front-loaded.

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 single required parameter fully documented by the schema and no output schema, the only real gap would be return shape, and the description does state it returns a per-action cost (details, ceo, marketing, ecommerce). It lacks detail on currency, per-store vs aggregate breakdown, or error behavior for invalid selections, but is adequate 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% and the nested selection object (ids vs tab+filters+deselected) is documented in detail in the schema, so the baseline of 3 applies. The description adds only 'for the selected stores,' which restates rather than extends the schema's meaning of selection.

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

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

The description opens with a specific verb+resource: 'Preview the credit cost of a reveal,' which separates it from the sibling revealStores (which presumably performs the reveal). It does not name that sibling explicitly, but the preview framing is unambiguous.

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

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

The phrase 'Preview the credit cost of a reveal' and 'nothing is charged and nothing is revealed' strongly imply this is a pre-flight check to run before revealing, but the description never names revealStores or getRevealStatus as alternatives, nor states when not to use it. Usage is implied rather than prescribed.

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, destructiveHint=false and openWorldHint=false, so 'Read only' adds nothing. The description does add that the response covers concurrency/credit balance, but says nothing about polling cadence, whether finished searches persist, or what statuses look like.

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 short sentence, front-loaded with the primary action, with no wasted clauses. The trailing 'Read only' is redundant with the annotations and slightly dilutes it.

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

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

With no output schema, the description carries the burden of explaining return values and only gestures at them ('status', 'credit balance'). For a polling/status tool it should say enough about result shape and timing to let an agent decide when to call it again.

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 single parameter storeIds is fully documented in the schema (100% coverage, including maxItems 300 and minimum 1). The description adds no additional meaning, so the baseline 3 applies.

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

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

States a specific verb ('Check') and two resources: the status of contact searches and the credit balance. It is distinguishable from siblings such as getRevealCost and revealStores, though the phrase 'started in the dashboard' is ambiguous about whether searches launched via revealStores are covered.

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 context ('searches you started') but never states when to choose this over getRevealCost or revealStores, nor any preconditions such as needing an in-flight search id. The agent must infer the polling use case.

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

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

Annotations already declare this a safe, read-only, closed-world operation, so the bar is lower. The description adds two pieces of context not in the structured fields: the response includes the set's criteria, and the tool is restricted to paid plans — a prerequisite the agent otherwise wouldn't 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?

Two sentences, zero filler, with the core action front-loaded and the gating constraint appended. Nothing could be removed without losing 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 tool with no output schema, the description covers what is retrieved (the set plus its criteria) and the plan requirement. A note on error behavior for an unknown or unpaid-plan id would close the remaining gap.

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

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

Schema coverage is 100% and the single parameter is already documented as "The signal set id from listSignalSets," which the description does not improve upon or contradict. Baseline 3 is appropriate when the schema carries the whole burden for one 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?

The description gives a specific verb and resource ("Get ... signal sets") plus scope ("one of your"), and "with its criteria" hints at the payload shape. It doesn't name listSignalSets or deleteSignalSet as siblings to distinguish against, so it stops short of a 5.

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

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

"Paid plans only" is a real eligibility gate that tells the agent when this call will fail, but there's no explicit routing to listSignalSets for discovering ids or to previewSignalSet/deleteSignalSet as adjacent alternatives. Usage is implied rather than stated.

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

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

Beyond the read-only, non-destructive annotations, it discloses the fixed result cardinality, recency scope, and currency localization. It omits the cadence and ordering of the 24 points, and 'Values use your currency' is ambiguous for the many non-monetary metrics.

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 front-load the operation, scope, and intended use without unnecessary wording. The currency sentence is brief and potentially useful, despite its ambiguity.

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 simple two-parameter schema, annotations, and explicit retrieval scope are sufficient for correct selection and invocation. With no output schema, the lack of point cadence, timestamp, and ordering details leaves some uncertainty about interpreting or rendering the returned series.

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 domain fully explained and metric constrained by a detailed enum, so the baseline is 3. The description reinforces that each call covers one store and one metric but adds no further parameter formats or metric-selection guidance.

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 precisely states that the tool retrieves the latest 24 points of one metric for one store, specifically for charting. This bounded time-series purpose distinguishes it naturally from siblings such as lookupStore and searchStores.

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 phrases 'for a chart' and 'one metric' provide a clear use case: rendering a recent single-metric series. It does not explicitly say when not to use it or name an alternative for broader store lookups or multi-metric analysis.

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

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

Annotations already declare this is read-only, non-destructive, and closed-world. The description adds useful behavioral context beyond that: pagination is capped at 100 per page, paid plans are required, and the tool is explicitly scoped away from store data. It does not describe error behavior, but that is a minor gap for a simple read operation.

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

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

The description is three short sentences, front-loaded with the core purpose, followed by the sibling alternative and the paid-plan constraint. Every sentence adds practical 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?

For a simple read-only tool with two fully documented parameters, annotations, and no output schema, the description supplies the essential context: what is returned, pagination behavior, plan restriction, and where to go for related store data. Nothing critical is missing 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%, so page and listId are already documented in the schema. The description adds meaning by clarifying that listId can refer to one watchlist or the blacklist and by showing how the id is used in searchStores' tab syntax. It does not add anything for the page parameter, but the extra listId context is useful.

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

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

The description states a specific verb and resource ('Get the domains of one watchlist or the blacklist') plus scope ('100 per page'). It also distinguishes the tool from searchStores by saying that searchStores is for store data, so an agent can route correctly without opening another 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 gives clear usage context: use this for domains and use searchStores with tab 'watchlist:{id}' for store data. It also notes paid plans only. It does not explicitly explain when to use a watchlist versus the blacklist or state the listWatchlists prerequisite in prose, but the main alternative is named.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds value beyond them by disclosing a plan-level access requirement and by describing the payload contents (signal catalog plus ICP columns) 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?

One sentence with no filler, front-loaded on the verb and resource. The trailing clause about the catalog and ICP columns is somewhat dense, but every part carries information an agent needs.

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

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

For a zero-parameter read tool with annotations covering safety and no output schema, the description supplies the return contents and the plan gating. Only the relationship to getSignalSet is left implicit, which is a minor gap.

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

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

The tool takes zero parameters, so the baseline is 4; the description correctly implies an unfiltered listing rather than suggesting any hidden 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?

States a specific verb and resource ('List your signal sets') and adds what the response contains (signal catalog and ICP columns usable in criteria). It does not explicitly distinguish itself from the sibling getSignalSet or explain list-vs-get, so it falls short of a 5.

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

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

The 'Paid plans only' clause gives a real eligibility precondition for calling it, but there is no explicit guidance on when to use this versus getSignalSet for a single set, and no stated exclusions or follow-up actions.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds the paid-plan entitlement constraint and discloses that the blacklist is included and that a domain count accompanies each entry — useful context beyond annotations, but nothing about ordering or volume.

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 what is returned and ends with the eligibility constraint. No redundant wording or restatement of the tool name.

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

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

For a zero-parameter read tool with full annotation coverage, the description supplies the essentials: what is listed, what is included (blacklist), the returned metric (domain count), and the plan restriction. It stops short of noting whether results are paginated or how the list is ordered, which a caller might still want.

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

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

The tool takes zero parameters, so there is no parameter semantics for the description to explain; the schema is trivially complete at 100% coverage. With no arguments to disambiguate, the description neither adds nor omits anything 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 gives a specific verb and resource set: listing watchlists plus the blacklist, with per-item domain counts. That distinguishes it from the sibling getWatchlist (single-item) and listSignalSets (different resource), 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?

The one usage-relevant statement is the 'Paid plans only' eligibility gate, which is genuinely useful. There is no explicit guidance on when to prefer this over getWatchlist or how it relates to the signal-set listing siblings, so routing is only implied.

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

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

Well beyond what the annotations cover: rate limits for both anonymous and OAuth callers, the fact that contacts are only populated for authenticated users, and the important semantic that co-located stores sharing a base domain return identical traffic and ad numbers via sharedMetrics. The one tension is the statement that the call "writes a lookup history row" against readOnlyHint=true; this reads as an audit-log side effect rather than a mutation of store data, so it is honest disclosure rather than a misleading claim, but it does soften the read-only guarantee.

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

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

Purpose is front-loaded in the first sentence, then response contents, then conditional behaviors, then limits — a sensible order. It is dense and the long enumeration of returned fields is heavy, but since there is no output schema that enumeration is doing necessary work rather than padding.

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

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

With no output schema, the description carries the whole burden of explaining what comes back and it does so: contact fields, decisionMakers under OAuth, sharedMetrics semantics for shared base domains, and rate limits per auth mode. An agent can predict the shape and cost of the call without any further documentation.

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

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

With a single parameter at 100% schema coverage, the schema already carries the meaning (domain, with full URLs accepted). The description adds no format or normalization detail for the domain argument beyond what the schema states, 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?

"Look up one ecommerce store by domain" gives a specific verb (look up), a specific cardinality (one), and the lookup key (domain), which implicitly separates it from the list-style searchStores and the revealStores siblings. It stops short of naming an alternative, so an agent must infer the boundary rather than read it.

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

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

Usage context is present but indirect: it explains that decision-maker contacts appear only with OAuth, and that anonymous access is capped at 20 lookups/hour per IP. It never states when to choose this over searchStores or revealStores, and there is no when-not guidance, so the routing decision 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=true, destructiveHint=false and openWorldHint=false, so the description's main job is to add context beyond them. It does that by disclosing the 80-store threshold, the exact return shape {"enough": true|false}, the no-persistence guarantee, and a paid-plan restriction — details absent from the annotations. It leaves out error behavior for malformed or empty criteria, which keeps it from a 5.

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

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

Four short sentences, front-loaded with the core check and threshold, then the return contract, then the non-persistence caveat, then the eligibility constraint. No redundancy, though the telegraphic "Paid plans only" fragment reads slightly clipped rather than intentionally concise.

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

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

For a two-parameter read-only preview tool with a fully documented nested criteria schema, the description covers what it does, its threshold semantics, its return value (no output schema exists, so stating it matters), and a plan-level restriction. Missing only failure modes for invalid criteria or unknown setId values.

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

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

Schema description coverage is 100% and the criteria object's recursive and flat forms, node types, and the setId purpose are all documented in the schema itself. The description only restates that the criteria are "candidate" and unsaved, adding little meaning 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 verb and resource: check whether candidate signal criteria match enough stores, with a concrete threshold (80 or more). It also explicitly contrasts itself with the saving sibling (saveSignalSet) by saying "It does not save anything," so an agent can distinguish it from the other signal-set tools without opening any schema.

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

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

The phrase "It does not save anything" plus "Paid plans only" gives a clear precondition and implied workflow: preview before persisting. It stops short of naming saveSignalSet as the follow-up action or stating what to do when "enough" is false, so it is clear context rather than explicit 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?

Beyond the annotations, it discloses the limited mutation scope—one domain—and the paid-plan requirement. It does not explain error behavior for an unknown list or absent domain, but those omissions are modest for this simple 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?

Two short sentences front-load the action, resource, scope, and plan restriction. There is no redundant or low-value wording.

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 flat, two-parameter mutation, the description and schema together provide the operation scope, access prerequisite, and precise parameter provenance. No additional return-value explanation is necessary for correct selection and 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%, including the exact-domain requirement and sources for both values. The description adds no parameter syntax or lookup guidance beyond that structured information, so the baseline score 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 and resource: removing one domain from a watchlist or blacklist. The single-domain scope also distinguishes it from whole-list operations such as deleteWatchlist.

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 clearly identifies the applicable task and adds the eligibility restriction, 'Paid plans only.' It does not explicitly contrast item removal with whole-list deletion or name an alternative, so selection guidance is not exhaustive.

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

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

Annotations already declare this is a non-readonly but non-destructive, closed-world mutation. The description adds genuinely useful constraints beyond that — an immutable target (blacklist) and a plan-level authorization gate (paid plans only) — but says nothing about what happens on a duplicate name, whether the change is reversible, or what the call returns.

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

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

Three short sentences, zero filler, with the core action stated first and the disqualifying constraints immediately after. Every sentence carries information an agent needs.

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

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

For a simple two-parameter mutation with annotations covering its safety profile and no output schema, the description covers scope, immutability, and plan eligibility. It is nearly complete; the only modest gap is expected error/conflict behavior on rename.

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%: 'name' is documented as the new name with a 100-char cap and 'listId' is documented as coming from listWatchlists. The description adds no additional meaning about validation, naming collisions, or how listId is obtained, so the schema carries all parameter semantics.

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

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

States a specific verb and resource ("Rename one of your watchlists") that is unambiguously distinct from sibling mutations like createWatchlist, deleteWatchlist, and update-style tools, and it immediately narrows scope by excluding the blacklist.

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

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

Provides two concrete gating conditions: the blacklist is not renamable and the operation is limited to paid plans, which tells an agent when not to attempt the call. It stops short of naming the alternative path a free-tier or blacklist user should take, so it is strong context rather than a full routing rule.

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 mark this as destructive and not read-only; the description goes well beyond them by quantifying the cost model (1 credit per store, +1 for unrevealed details, 0 for already-revealed stores) and the failure behavior (insufficient credits returns cost and balance with nothing charged). These are the details an agent needs to avoid unwanted spend.

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

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

Front-loads the cost warning in the second sentence, which is the single most important fact. Dense but every clause carries operational meaning; the middle sentences are long and run several pricing rules together, which mildly hurts scanability.

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?

Covers prerequisites, per-action pricing, idempotent re-reveal, and the insufficient-credit outcome despite having no output schema. Nothing an agent needs to call this safely and correctly is missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real meaning the schema lacks: what 'details' unlocks (profile links, buying signals, phone) and that ceo/marketing/ecommerce launch a decision-maker search at a stated price. The 'selection' object itself is left to its schema 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?

States a specific verb and resource ('Reveal data for stores') and immediately flags the distinguishing trait (spends credits). The four action values are each explained in terms of what they unlock, so an agent knows exactly what the tool does and how it differs from getRevealCost and getRevealStatus.

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

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

Explicit routing: call getRevealCost for the same selection first, tell the user the cost, and never call without confirmation. It also names getRevealStatus as the follow-up tool for contact searches, so both the prerequisite and the continuation are covered.

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

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

Goes well beyond the destructiveHint=true annotation by naming exactly what is destroyed (all signals, legacy categories, ICP filters), what survives (saved custom SQL conditions, joined with AND), and what the response reports (preservedConditions). The only gap is that it doesn't discuss reversibility or error behavior when the plan limit is hit.

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?

Six short sentences, front-loaded with the create/update fork, then the destructive semantics, then the preservation caveat, then the recommended prerequisite. Every sentence carries distinct information; nothing is redundant with the title or schema.

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

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

For a destructive mutation with a nested criteria object and no output schema, the description supplies the missing return information (preservedConditions) and the loss/survival semantics an agent needs before invoking it. Nothing material is left unstated given the annotations and 100% schema coverage.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema does not: setId's presence switches the operation to a full criteria replacement, and setName only matters when creating. It also points out that criteria must use the previewSignalSet format, which the schema only repeats.

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

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

States a specific verb+resource pair ('Create a signal set') and immediately covers the dual mode (create vs. replace) with concrete conditions. It is clearly distinguishable from siblings previewSignalSet and deleteSignalSet, which are named or implied as different operations.

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

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

Explicitly says when to omit setId vs. supply it, directs the agent to run previewSignalSet first to validate criteria, and notes the paid-plan restriction and plan limit. Both the branch condition and the prerequisite step are stated rather than inferred.

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

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

Beyond the read-only annotations, the description discloses important behavior: 30 rows per page, masked values for unrevealed stores, exact total versus totalAtLeast fallback, hasMore pagination, and sharedMetrics for stores sharing a base domain. These are substantive operational details that an agent would not get from the annotations 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 long but dense and front-loaded: it starts with purpose and page size, then covers masking, default columns, count fallback, pagination, and shared metrics in a logical order. Every sentence contributes useful behavior or output context for a complex search 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?

With no output schema, the description does the necessary work of explaining the returned row shape, default columns, reveal object, pagination behavior, total fallback, and sharedMetrics. It is complete enough for an agent to call and interpret results correctly.

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

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

Schema description coverage is high at 83%, so the baseline is 3. The description adds useful meaning about the default row fields, the effect of omitting columns, and that ["*"] returns all columns plus the full reveal object, though it does not add much detail for filters, sort, or tab 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 and resource: "Search the store catalog" and explains that it returns paginated catalog rows. It is clear what the tool does, but it does not explicitly distinguish this search/list operation from siblings such as lookupStore or exportStores.

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 operational usage guidance, such as using the columns argument, using hasMore for pagination, and not reporting totalAtLeast as the match count. However, it does not explicitly say when to choose searchStores over lookupStore, exportStores, or revealStores.

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=false, openWorldHint=false, and destructiveHint=false. The description adds valuable context beyond that: the recipient team and a concrete rate limit of 5 messages per hour. It does not cover success/failure behavior or permission requirements, so it falls short of the top score.

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, front-loaded with the action and recipient, then the operational limit. No wasted wording.

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 tool with no output schema, the description covers purpose, audience, and rate limiting. It is nearly complete, though it could mention what happens after submission or whether authentication is required.

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 single message parameter is documented in the schema. The description adds no syntax, formatting, or length guidance beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb and resource: send a feedback message, and names the recipient team (Ecommerce Leads). No sibling tool handles feedback, so this is unambiguous without further differentiation.

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

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

Usage is implied by the tool name and description, but there is no explicit when-to-use guidance, no exclusions, and no alternatives. For a simple one-off feedback channel this is acceptable but not strong.

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

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

Annotations already establish that this is a non-read, non-destructive, closed-world mutation. The description adds genuinely new behavioral facts beyond them: the tool errors if the store was never revealed, and a store inside a revealed group is accepted at no credit cost. It stops short of covering idempotency of re-setting a status or what the response contains, which keeps it from a 5.

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

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

Four short sentences, front-loaded with the action and then the prerequisite and cost caveat. Every sentence carries an operational constraint; there is no filler or restatement of the tool name.

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

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

For a two-parameter mutation with no output schema, the description covers the precondition, the error path, and the credit implication, which is what an agent needs to call it safely. It could still say what happens on an invalid or unknown storeId and whether status changes are reversible, but the remaining gap is small.

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 50% schema description coverage, the storeId provenance note in the description largely restates the schema's own description of that field. The status parameter carries no explanation in either place beyond its self-explanatory enum values, so the description adds little semantic meaning over the structured input definition.

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: 'Set the outreach status of one store that you revealed.' It bounds the scope to a single store and ties it to the reveal workflow, which separates it cleanly from siblings like revealStores, searchStores, and addToWatchlist without needing 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?

It states the exact source of the required id ('Use the storeId from a searchStores row') and an explicit prerequisite with a named alternative ('Use revealStores first'), plus the failure condition if the prerequisite is skipped. This is explicit when-to-use and when-not-to-use guidance rather than inference.

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