Name Etsy tags over the 20-character limit when Etsy refuses them - #1553

Summary

Etsy refuses a listing tag longer than 20 characters with "There was a problem with /tags : cannot be more than 20 characters", without saying which tag. Models then guess, and the same call fails again. This PR appends a hint to that error naming each tag over the limit and its length, so the model can fix the call in one turn. It also corrects the tags description in the Etsy tools: the 20-character limit applies to English listings only.

Why not refuse such calls before they reach Etsy

That was the first plan. A read-only production check (counts only, last 14 days, etsy_create_listing_draft and etsy_edit_listing) ruled it out:

• 109 successful calls had tags of 21 to 30 characters, and the listing Etsy returned kept them at full length.
• 50 calls were refused with the error above, all with tags of 21 to 23 characters.
• The two groups never share a workspace. Every workspace where Etsy accepted long tags has listings in German, French, Italian or Spanish. Every workspace where Etsy refused them has en-US listings.

The limit therefore depends on the listing language, which the edit and create tools do not know before the call. A check before the call would have blocked those 109 calls Etsy accepts. The hint only runs after Etsy has already refused the call, so it never stops a call Etsy would take.

Design

• ErrorHintInput (mcp-server/error-hints.ts) gets an optional args field: the arguments of the call. The REST/engine error path in DynamicMcpTools.executeTool passes them. Every existing rule ignores it.
• A new rule fires only when the error comes from Etsy (host *.etsy.com, or a connector installed from the etsy catalog adapter) and the error text matches /tags : cannot be more than N characters. The limit N comes from Etsy's own message.
• The hint quotes only the tags over the limit, never any other argument. Tags are trimmed and counted in code points, and a quoted tag is cut at 60 characters. If no tag in the arguments is over the limit, the hint states the rule without quoting anything.
• Example: tag "handmade ceramic coffee mug" has 27 characters; Etsy allows at most 20 characters per tag on English listings. Shorten or replace it and call again with the other tags unchanged.
• As with the other hints, the call log keeps Etsy's own error and not the hint, so the tags are not copied into another column.
• No other connector or adapter is affected: the rule needs Etsy's host or the etsy adapter plus Etsy's exact error text.

Reaching installed connectors

• The hint is server code. Every Etsy connector, including ones installed long ago, gets it with the deploy.
• The description change touches only parameters descriptions (no endpoint mapping). That is the safe class the catalog auto-sync applies when the app starts, so installed connectors get it without the customer clicking "Apply update".

Cloud and self-hosted

Both deployments behave the same. On self-hosted, the description change is applied when the app starts unless the operator set CATALOG_AUTOSYNC=false, in which case it arrives with the next catalog update. The hint does not depend on that setting.

Changes

• packages/backend/src/mcp-server/error-hints.ts: optional args on ErrorHintInput; an Etsy tag-length rule; a small exported helper overlongListItems.
• packages/backend/src/mcp-server/dynamic-mcp-tools.ts: passes the call's arguments to deriveErrorHint on the engine error path.
• packages/backend/src/adapters/intl/etsy.json: the tags description of etsy_create_listing_draft, etsy_edit_listing, etsy_add_listing_translation and etsy_replace_listing_translation now says the 20-character limit is for English and that other languages may have longer tags. No maxLength was added.
• Tests: error-hints.spec.ts (tags named with lengths, nothing else quoted, limit taken from Etsy's message, emoji counted as one character, long tag cut, no quote without arguments, no hint for another host); dynamic-mcp-tools.spec.ts (end to end through the executor with a catalog Etsy connector); adapters/intl/etsy.write-tools.spec.ts (every Etsy tool with tags states the English-only limit and has no length cap).

Type

• Bug fix
• New feature
• Documentation
• Refactoring
• Performance improvement
• Other (describe below)

Testing

• Added/updated unit tests
• Tested manually (describe steps below)
• No tests needed (explain why)

Commands run, with real results:

Checklist

• My code follows the existing code style
• I have tested my changes locally
• I have updated documentation (if applicable): not applicable, the hint is advisory text on an error and the tool descriptions are the documentation the model reads
• All existing tests pass (npm test): all but one database-backed spec that also fails on main locally (see the table)
• This PR has a descriptive title

Related Issues

Follows #1527 (Etsy's 140-character title limit). Found in the daily Cloud check of 2026-11-06.