fix(vtex): surface curated param descriptions to the agent

[guitavano]

Problem

An agent using the VTEX MCP couldn't figure out it needed f_RnB to count sales for a coupon/promotion (e.g. FICA10 / "Pop retenção DECO"). Root cause: the agent gets no description at all for that parameter.

The generated Zod schemas are produced with metadata: false in openapi-ts.config.ts (comment: "descriptions are not read at runtime"). That's inaccurate for an MCP — the input schema is read at runtime: it becomes the JSON Schema sent to the LLM. With metadata off, every f_ filter on every VTEX tool reaches the agent as a bare f_RnB: string, with no meaning and no value format. The rich JSDoc in types.gen.ts never leaves compile time.

Why not just flip metadata: true?

Measured it:

	bundle	notes
baseline (metadata: false)	4.70 MB
metadata: true (regen)	6.05 MB	+1.57 MB / +35%

Regenerating also can't be isolated: download-schemas pulls current upstream, which drifts (~10k lines across 72 files), renames an operation (postApiAuthenticator → postApiAuthenticatorV1StorefrontUsers) that breaks a registry.ts reference, and adds new modules. That's a separate "sync schemas" concern, not this fix.

This PR

Layer curated descriptions onto the flattened input schema in the tool adapter (applyParamDescriptions), keyed by tool id → field. Covers the VTEX_LIST_ORDERS params where the omission actually hurts, written richer than the raw OpenAPI text:

• f_RnB — explains it takes the promotion id, not the coupon code, and that you resolve FICA10 / a promotion name via the promotions tools first.
• f_creationDate / f_invoicedDate — the creationDate:[<from> TO <to>] UTC range format.
• f_status — the closed set of valid statuses.
• q — what full-text search matches.

Adding coverage later = one line in param-descriptions.ts.

Impact

• Bundle unchanged: 4.70 MB (+1.5 KB for the new module).
• f_RnB and the other curated params now carry descriptions in the agent-facing JSON Schema (verified end-to-end via z.toJSONSchema).
• No upstream schema drift, no generated-code changes.

Tests

bun test server/tools/registry.test.ts → 53 pass. New regression tests assert the curated descriptions reach the JSON Schema, that overriding a field keeps it optional, and that tools without overrides are returned unchanged.

Follow-up (out of scope)

Whether to do a full metadata: true regen for blanket coverage is a separate decision — it needs the +1.57 MB bundle accepted and the upstream drift / renamed export handled deliberately.

🤖 Generated with Claude Code

---

Summary by cubic

Exposes curated parameter descriptions to the agent so VTEX filters like f_RnB, date ranges, status, and q are clear and usable. Fixes the missing metadata that blocked counting sales by coupon/promotion, without increasing the bundle size.

• Bug Fixes
  • Layer curated descriptions onto tool input schemas via applyParamDescriptions.
  • Covers VTEX_LIST_ORDERS: f_RnB (promotion id, not coupon), f_creationDate/f_invoicedDate range format, valid f_status values, and what q searches.
  • Tests verify descriptions in the agent-facing JSON Schema and that fields remain optional.
  • No schema regen; bundle stays ~4.70 MB (+~1.5 KB).

^{Written for commit b55084a. Summary will update on new commits.}

[guitavano]

Consolidado no #525 (PR único cobrindo sync + metadata + overrides curados).