Undercart

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), yet the description still adds real behavioral context: the revenue estimate vs. preliminary-range fallback for un-researched stores, an explicit error on unknown domains, and credit consumption. It stops short of describing result ordering or what an empty result set looks 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?

Three compact sentences, front-loaded with the matching definition, then usage, then failure/credit conditions. 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?

No output schema exists, and the description covers the match criteria, the unknown-domain failure, and the credit cost, which is most of what an agent needs. It leaves the return shape (list of store records, presumably) implicit, which is a minor gap for a read-only lookup 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 coverage is 100%, so 'domain' and 'limit' (default 10, max 15 on Free, hard cap 50) are fully documented in the schema already. The description adds the semantic of what counts as 'similar' for the matching revenue figure, but nothing about the domain normalization or limit behavior, so the baseline 3 is right.

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 ('Find Shopify stores similar to a given store') and immediately defines the matching rule: same category plus a 0.5x-2x annual-revenue window. That specificity separates it from get_store (single lookup) and search_stores (keyword search) without needing to open either schema.

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

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

'Useful for competitive sets and lookalikes' gives a use context, and 'Uses search credits like search_stores' hints at a cost relationship with a sibling. However, it never states when to prefer this over search_stores, nor any exclusion such as what happens for a domain that is known but has no close matches.

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=true, so the safety profile is covered. The description goes well beyond that by disclosing the on-demand research kickoff and wait behavior, retryAfterSeconds semantics, the non-Shopify error, daily research allowance, the enriched:false fallback with dataNote, redirect naming, and the monthly store-lookup quota mechanics on capped plans.

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

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

The description is dense but front-loads the core purpose (what profile data is returned) before moving to research/retry behavior, error cases, and quota rules. Every sentence carries needed information, though the single long paragraph is heavier than ideal and could be broken into clearer sub-clauses.

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

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

With no output schema, the description carries the full burden and does so thoroughly: it lists the returned profile fields, explains the research/retry flow, the non-Shopify error, the enriched:false fallback, and the quota model. An agent has enough information to call it and interpret both normal and edge-case responses.

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 is a single required parameter with 100% schema description coverage, and the schema already states that the domain is normalized automatically. The description adds no syntax or format detail beyond the schema, 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?

The description states a specific verb and resource: get the intelligence profile for a single Shopify store by domain. It enumerates the profile contents (revenue, orders, plan, tech stack, ads, traffic, etc.), which implicitly and clearly differentiates it from the narrower siblings get_store_ads, get_store_email, and get_store_emails, as well as from search_stores/find_similar_stores.

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 explains the context of use (single store by domain), what happens when the store hasn't been researched (starts research and waits 15-30s), the retryWithAfterSeconds pattern, the error for non-Shopify domains, and quota consumption. It does not explicitly name alternative sibling tools, but the usage conditions are otherwise 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?

Beyond the readOnly/openWorld/destructive annotations, it discloses several non-obvious traits: imageUrl/videoUrl links expire in ~1 day, creative lookups are cached ~1 day, stores with enriched: false return no ad data, and calls are metered once per store per month. These are exactly the cost, freshness, and data-availability caveats an agent needs before invoking.

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

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

Front-loaded with the data domain, then the conditional creative mode, then freshness/metering caveats — every sentence carries information. It is dense and slightly run-on in the first sentence, but nothing is padded.

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

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

With no output schema, the description carries the full burden and delivers: it enumerates returned fields, explains the two response modes, and covers caching, link expiry, enriched:false emptiness, and metering. An agent has everything needed to call and interpret this 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 baseline is 3. The description reinforces that omitting platform changes the return shape and that limit bounds creatives, but this largely restates the schema's own platform and limit descriptions rather than adding format or constraint detail.

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

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

The description states a specific verb+resource (store advertising activity) and precisely enumerates both return modes: cross-platform presence (active, ad count, estimated monthly spend) and per-platform creatives with named fields. It distinguishes itself from siblings by noting it is "metered like get_store", signalling a different data domain than get_store_email or list_store_technologies.

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 conditional usage: specify platform to get actual creatives, omit it for the presence summary only, and it names the metering sibling get_store for cost comparison. It stops short of explicit when-not-to-use guidance against the other eight siblings, so it is clear context rather than full 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?

Annotations already establish the read-only, non-destructive, non-open-world safety profile, so the bar is lower. The description adds genuinely useful context beyond that: the call is free/not metered, the HTML payload is a large raw blob that is sanitized, and the plain-text body is preferable for reading.

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

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

Front-loaded with the resource being fetched, then the return content, then the billing note. Dense but every clause carries information; the em-dash-heavy phrasing is slightly harder to scan but not wasteful.

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

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

With no output schema, the description correctly describes what comes back (plain-text body, optional htmlBody) and covers all three parameters. The only shortfall is that it never addresses how this differs from get_store_email_html, leaving sibling selection partly ambiguous.

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 semantic value for includeHtml — what it returns (htmlBody), when to enable it (visual re-rendering/artifact), and the size/tradeoff warning — plus it reinforces emailId's provenance.

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

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

The description names a specific retrieval action on a specific resource ('One captured marketing email, by store domain and email id') and identifies the sibling that produces the id (get_store_emails). An agent can distinguish this single-item fetch from the list-producing sibling without opening either schema.

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

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

It clearly states the precondition (the id comes from get_store_emails) and gives a when-to-use rule for includeHtml ('only set when re-rendering the email visually'). It does not, however, acknowledge the closely related sibling get_store_email_html, which an agent might otherwise consider an alternative — the one obvious routing gap.

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 readOnly/destructive/openWorld, but the description adds real behavioral detail beyond them: the HTML is sanitized, images are rewritten, and no plain-text body is included. This tells an agent what the payload actually contains.

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 tight sentence that front-loads the key fact (returns HTML) and immediately qualifies scope (sanitized, image-rewritten, no plain text). No waste.

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

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

With no output schema, the description carries the return-value burden and does so well, stating the HTML-only nature and the sanitization/rewriting transformations. For a simple two-param read tool with readOnly annotations, this is nearly 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%, so both parameters (domain, emailId) are already documented in the schema, including that emailId comes from get_store_emails. The description adds no parameter meaning beyond that, 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?

States a specific verb and resource: returns one captured email's sanitized, image-rewritten HTML. It differentiates itself from get_store_email by noting it is a companion that emits HTML and omits the plain-text body. The distinction is clear at a high level, though it doesn't spell out what get_store_email itself 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 phrase 'used by the email-viewer widget' and 'Internal companion to get_store_email' implies the rendering context in which to use it, but there is no explicit when-to-use/when-not-to-use guidance or named alternative condition. Usage 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?

Annotations already cover the safety profile (read-only, closed-world, non-destructive), and the description adds genuinely useful behavior beyond them: newest-first ordering, an unknown-domain error, and metering semantics ('once per store per month'). These are the details an agent needs to decide whether to spend a call.

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 payload description is front-loaded and every clause adds information (fields, ordering, follow-up tool, error, metering). It is slightly dense/run-on in the opening sentence, but nothing is wasted.

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

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

There is no output schema, so the description carries the return-value burden and does so by listing the returned fields and their ordering. Combined with the error and cost notes, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so domain normalization and the limit default/max are already documented in the schema. The description adds no parameter-level syntax or constraints beyond that, 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+resource (marketing/newsletter emails captured from a store) and enumerates exactly what comes back: subject, sender, snippet, discount codes, received date, plus cadence. It is clearly distinguishable from get_store_email (single email body by id) and get_store.

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 routes the agent to the sibling for a follow-up need ('Each email's full body is available from get_store_email by id') and flags failure conditions ('Returns an error if the domain is unknown'). It does not explicitly frame when a different tool should be used instead of this one, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: it is free/not metered and returns each category with a store count and category-page link. It does not discuss pagination or ordering, but for a no-parameter list tool this is solid extra 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?

The description is a single efficient sentence with the core action and resource front-loaded, followed by output content and cost. Every clause adds useful information 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?

For a zero-parameter, read-only listing tool with no output schema, the description supplies the missing return-value shape (categories, store counts, category-page links), ties the output to search_stores, and notes the cost model. In combination with the annotations, an agent has everything needed to call and interpret this tool correctly.

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

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

There are zero parameters and schema description coverage is 100%, so the schema has no parameter semantics to explain. Per the baseline for a zero-parameter tool, a 4 is appropriate; the description does not need to add parameter meaning and correctly avoids doing so.

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 ('List the store categories') and immediately ties it to the sibling tool search_stores by saying these are the categories it accepts. It also states what each returned item includes, so the agent can distinguish this from search_stores without opening either schema.

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

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

The relationship to search_stores implies the tool is used to discover valid category values before searching, but there is no explicit when-to-use statement, no exclusions, and no direct comparison to alternatives like find_similar_stores or get_store. The 'Free (not metered)' note is useful cost context but does not function as usage 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 mark this as a safe read, yet the description adds substantial behavior the agent could not infer: status semantics (active, not_seen meaning not proof of removal, removed meaning two separate reads missed it), sinceOrEarlier semantics, date formats (YYYY-MM-DD or YYYY-MM), the enrichment caveat, and the error condition for unknown domains. Cost/metering behavior is also disclosed, which directly affects whether an agent should call it.

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

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

Dense single paragraph, front-loaded with purpose and grouping before the status/date semantics. Every sentence carries information (status meanings, date formats, enrichment caveat, metering), though the run-on structure across semicolons and em-dashes makes it slightly harder to scan than an itemized form would be.

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

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

No output schema exists, but the description adequately conveys the return shape: technologies grouped by category, each with status, first-seen and last-seen values, plus the store plan. Combined with error and metering notes, an agent has everything needed to decide and call 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?

There is a single parameter with 100% schema description coverage, so the schema already documents the domain format and automatic normalization. The description only restates that the lookup is by domain and adds no syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema does the work.

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

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

States a specific verb (list) and resource (detected technology/app stack) scoped to a single store by domain, with the grouping (by category) and the Shopify plan included. It is clearly distinguishable from siblings like get_store or get_store_ads, which cover different data about the same store.

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?

Makes the usage context explicit: one store per call, by domain, errors on unknown domains, and metered like get_store (once per store per month). It also clarifies the enriched:false case (HTTP Archive public crawl data). It stops short of naming a sibling alternative for related needs, but no exclusion is needed here since siblings answer different questions.

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 readOnly/destructive annotations, it discloses key behavior: all filters AND together, many filters restrict results to the few thousand deeply researched stores, results are ranked by estimated revenue, and Free-plan searches consume credits with free identical repeats.

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

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

The description is front-loaded with the core search purpose and remains dense rather than padded across 39 parameters. The long filter inventory is useful but could be structured more scannably; still, almost every sentence carries actionable 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 complex 39-parameter search tool with no output schema, it covers result shape and ranking, filter interaction, coverage limitations, example usage, and credit implications. An agent has enough context to invoke it correctly without opening sibling tools.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds useful cross-parameter semantics such as AND behavior, omit-to-broaden guidance, and the reseller-specific brandsMin/ownBrandMax strategy. It does not separately explain every parameter, but it meaningfully enriches the most strategically important ones.

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: searching Undercart's Shopify store catalog with the store explorer's filters. It clearly distinguishes this from get_store-style siblings by describing catalog-wide search, filtering, and ranked results.

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

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

It gives explicit when-to-use guidance, including omitting sparse filters to search the full ~700k catalog, using brandsMin/ownBrandMax for resellers instead of description phrases, and preferring one well-filtered search over many narrow ones due to credit costs.

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