Growtsy — free Etsy seller tools

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open world). The description adds meaningful context beyond them: the source of truth ('Etsy's published rates') and the modeling assumptions that bound the result. It stops short of describing the output shape or rounding/precision behavior.

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

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

A single compact sentence that front-loads the subject (the fee components) and closes with the assumptions. No filler or redundancy.

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

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

For a read-only calculator with no output schema, the description reasonably implies a per-component breakdown and states its assumptions. It could be stronger by confirming the return shape (itemized vs. total) and that the result is in USD, but nothing essential is missing.

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

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

Schema coverage is 100% and all three parameters carry descriptions, so the schema does the heavy lifting. The description adds no extra parameter meaning such as currency handling or country-code matching behavior, 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 names a concrete resource ('Etsy's fees for one order in the seller's country') and enumerates the fee components it computes, so the agent knows exactly what will be produced. It doesn't explicitly contrast with the sibling tools, but those are all check/audit/idea tools, so confusion is unlikely.

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?

Scope boundaries are implied through the stated assumptions ('no sales tax on the order and no Offsite Ads'), which tells the agent when the numbers apply, but there is no explicit when-to-use or alternative guidance. Adequate but minimal.

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 readOnly, idempotent, non-destructive, open-world behavior, so the description's job is lighter. It adds real value by disclosing what data are fetched, that Etsy's published title/tag rules are applied, and the notable output contract that only the *first* thing to fix is returned rather than a full report.

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

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

Three sentences, with the resource and returned fields front-loaded before the usage triggers. The field enumeration is somewhat list-heavy but each item conveys what the agent can expect back, so little 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?

With no output schema, the description correctly carries the burden of describing returns (field set plus the 'first thing to fix' result), and it supplies use cases and rule application. Nothing material for correct invocation is missing.

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

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

Schema coverage is 100% with a single required parameter already documented as an Etsy listing link or listing number. The description adds no parsing details, accepted variants, or error behavior 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?

States a specific verb and resource ('Reads one Etsy listing from Etsy's API') and enumerates the returned fields (title, tags, photos, video, expiry, renew, favorites, AI mention). This is clearly distinct from siblings like etsy_shop_audit or etsy_rank_check, which operate on different subjects.

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 concrete trigger phrases ('is my listing set up right?', 'when does my listing expire?') that map intent to this tool. It does not explicitly exclude or reference alternatives such as etsy_shop_audit for shop-level checks, so routing at the boundary 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 cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is lower. The description still adds real behavioral context beyond them: prices are counted across currencies without conversion, and search volume is structurally unavailable from Etsy's API. Missing rate/cost or pagination/cap details on volume of listings sampled, 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?

Two sentences, both earning their place: the first front-loads what comes back, the second pre-empts the obvious wrong expectation. No filler, no restatement of the title.

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

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

Only two simple non-enum parameters and no output schema, and the description compensates by enumerating return contents in detail. It also closes the biggest gap an agent would hit (no search volume, no demand verdict), so nothing needed to call or interpret the tool is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in structured form. The description reinforces 'the phrase' and notes non-USD listings are included, which lightly touches the 'physical' filter's intent but never clarifies it. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

Names the resource (facts from one Etsy search) and enumerates the exact outputs: active listing count, price quartiles/median, shared tags and title phrases, and the shops behind them. The output enumeration implicitly separates it from siblings like etsy_tag_ideas (ideas, not observed data) and etsy_shop_audit (shop-level, not phrase-level). No ambiguity about what an agent gets back.

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?

Clearly frames the tool as a raw-facts snapshot and explicitly excludes two expectations: 'No demand or saturation verdict and no search volume.' That negative guidance is genuinely useful. However, it never names an alternative sibling (e.g. etsy_rank_check or etsy_tag_ideas) or states the condition under which an agent should prefer this over them.

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

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

Annotations already declare readOnly/idempotent/openWorld, and the description adds genuinely new behavior: results are capped at the first 100 active listings in relevance order, and beyond that the tool reports 'not in the first 100'. It also discloses that results may diverge from what a shopper sees on etsy.com, which matters for interpreting output.

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 core behavior in the first clause, followed by the 100-result cap and a shopper-difference caveat — all sentences carry information. The opening sentence is dense enough that it takes effort to parse, but nothing is redundant.

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

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

With no output schema, the description carries the return-value burden and does so: it names the position, the missing words from title/tags, and the sentinel result beyond rank 100. Minor gaps remain (rate limits, what happens if neither url nor shop is resolvable), but an agent has enough to invoke 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 the baseline is 3; the description goes slightly beyond by clarifying that 'url' targets a single listing while 'shop' targets a shop's listings, matching the either/or wording in the schema. It does not add format examples for the Etsy URL, which keeps it from a 5.

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 precise verb+resource: the rank position of a listing (or shop's listings) for a search phrase, plus which query words are missing from title/tags. This is clearly distinguishable from siblings like etsy_listing_check, etsy_niche_check, or etsy_tag_ideas, which address different questions.

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 only implied — an agent can infer you call this to audit keyword ranking for a listing or shop. There is no explicit when-to-use, no named alternative, and no statement of prerequisites such as API key or call cost. The caveat that etsy.com search differs per shopper hints at interpretation limits but not tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description needn't restate safety. It does add real behavioral detail beyond them: a hard cap of 100 active listings, that only the shop's first problem is surfaced with a count, and that the sales figure is lifetime shop total rather than per listing. Auth requirements and rate-limit behavior are not mentioned.

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

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

Three sentences, front-loaded with the action and capped by return-value detail; every clause carries information. The lifetime-vs-per-listing parenthetical is slightly dense but prevents a real misreading, so it earns its place.

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

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

With no output schema, the description carries the return-shape burden and does so well: first problem, affected-listing count, per-listing issues, and sales count. It leaves open what happens for shops with more than 100 listings and how API failures are surfaced.

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 'shop' parameter already documents 'name or shop link', so the schema does the work. The description adds no syntax, normalization, or edge-case guidance for the parameter, which matches the baseline 3 for high-coverage schemas.

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 verb+resource: reads up to 100 active listings of a shop and checks them against Etsy's title, tag, and photo rules. That is far more precise than a generic 'audit'. It does not name a sibling to contrast with (e.g., etsy_listing_check for a single listing), so it stops short of 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?

Two concrete trigger questions ('why is my Etsy shop not getting sales?' and 'what should I fix first?') make the intended use unambiguous. There are no explicit exclusions or named alternatives, so an agent must infer that per-listing diagnosis belongs to etsy_listing_check.

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

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

The annotations already establish that the tool is read-only, idempotent and non-destructive, yet the description also adds a non-obvious domain fact: 'No shop found' does not mean the name is available, because Etsy never reuses the names of closed shops. That caveat directly affects how an agent interprets the results and cannot be found in any structured field.

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

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

Two tight sentences, with the scope stated first and the critical interpretation caveat immediately after it. No filler and no repetition of the title.

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

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

For a one-parameter, read-only tool, the description covers the scope and the main interpretation pitfall well. But with no output schema, the description is largely silent about the shape of the results: how rule violations and availability are reported per name, and whether a per-name breakdown comes back.

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 schema already documents the single 'names' parameter, including the maxItems of 6 and the string-or-array union. The description's 'up to 6 shop names' only restates that limit, 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?

It names a specific verb and resource ('Checks ... shop names against Etsy's shop name rules') and states the batch limit of 6. No sibling tool covers this task: fee_calculator, listing_check, niche_check and rank_check all ask different questions, so the agent can choose it 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 usage is only implied: the 6-name cap and the availability framing suggest pre-registration validation, but the description never states when to prefer this tool over the siblings, nor does it set out prerequisites or exclusions. An agent must infer the context from the tool name alone.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so safety is covered. The description adds meaningful context beyond that: it caps input at 5 shops and explicitly discloses a negative capability ('No revenue estimate'), preventing an agent from over-promising revenue figures. Return format and error behavior for invalid shop names are not covered.

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 compact sentences, front-loaded with what is returned and immediately followed by scope caveats and usage. Every clause carries information; the parenthetical on transaction_sold_count is dense but earns its place by preventing a common misinterpretation.

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 describing return values and does so by enumerating the four metrics plus the explicit absence of revenue. For a single-parameter, read-only lookup this is nearly complete; only the response shape and handling of invalid or missing shops is unaddressed.

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 schema already documents the shops parameter, including the array-or-comma-separated-string forms and the maxItems of 5. The description reinforces the 5-shop cap and clarifies the shop-level semantics of the sales figure but adds no new syntax or format guidance. Baseline 3 is appropriate.

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

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

States a specific verb and resource: returns Etsy shop-level sales count, active listings, favorites and opening year for up to 5 shops. It also disambiguates from siblings by scoping to shop-level metrics rather than audits, rank checks, or top-shop lists, and clarifies that transaction_sold_count is total shop sales, not per listing.

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 use cases: 'how many sales does this Etsy shop have?' and comparing competitors, which tells the agent when to reach for it. It stops short of naming alternatives or exclusions, so an agent choosing between this and etsy_shop_audit or etsy_rank_check must infer the boundary.

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

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

Annotations already declare readOnly, openWorld, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral facts: the sample is capped at the first 100 listings, tags are counted once per listing, and there is deliberately no search-volume data because Etsy's API doesn't expose it. That last note preempts a likely wrong expectation, which is exactly the kind of context annotations can't carry.

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, and the core output (tags plus a starting set) is front-loaded before the caveat. The parenthetical about search volume earns its place by preventing a false assumption.

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 returns, and it does: tags, title phrases, per-listing counting, and a 13-tag starter set. What's missing is the exact response shape — whether counts are returned as frequencies, whether title phrases are separated from tags. Adequate but not fully closed.

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?

One parameter at 100% schema coverage, so the schema already explains 'query' as 'What the seller sells'. The description reinforces this by describing the input as 'a phrase', but adds no format, length, or example guidance. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific extraction: tags and title phrases harvested from the first 100 listings for a phrase, deduplicated per listing, plus a 13-tag starting set. That is a concrete verb+resource an agent can match against siblings like etsy_niche_check or etsy_rank_check. It stops short of explicitly contrasting itself with those siblings, so no differentiation credit.

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

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

There is no explicit when-to-use or when-not-to-use statement, and no sibling is named as an alternative. The only routing signal is implicit — that this is tag/keyword research rather than a validation or ranking check. An agent must infer the use case from the purpose sentence alone.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuinely useful behavioral scope beyond that: only the first 100 active listings are examined and they are in relevance order, which materially affects interpretation of the counts. It omits any mention of rate limits or result truncation warnings beyond the 100-listing cap.

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

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

Two tight sentences: the first front-loads the mechanism and the return payload, the second front-loads the use cases. No filler or redundancy.

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

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

No output schema exists, but the description enumerates the returned fields (per-shop listing counts, sales count, opening year), and it discloses the 100-listing sampling window that bounds those numbers. That is sufficient for correct invocation and interpretation.

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 both parameters (query, physical) are already documented in the schema, establishing the baseline of 3. The description implies the query drives a relevance-ordered listing search but adds no syntax, example, or clarification of how 'physical' alters returned shops.

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 mechanism ('Runs one Etsy search') plus precisely what is returned ('the shops behind it: listing counts per shop, Etsy's shop sales count and opening year'). This clearly separates it from siblings like etsy_shop_sales (single shop) and etsy_niche_check, so an agent can route without opening 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?

Provides concrete usage triggers: 'who sells <product> on Etsy?' and 'who are my competitors?'. It does not name an alternative tool or state when NOT to use it (e.g. for a single known shop, use etsy_shop_sales), so it stops short of explicit routing guidance.

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