feat(vtex): expose param descriptions to the agent (sync client + Zod metadata) - #525
Merged
Merged
Conversation
Regenerates the hey-api client from the latest VTEX OpenAPI schemas.
Upstream renamed several operations and removed two; this reconciles the
tool registry so no tool references a now-undefined SDK export.
Renamed operations (registry references updated):
- punchout: {get,post}ApiAuthenticatorPunchout* -> *V1Punchout*
- vtex-id: postApiAuthenticatorStorefrontUsers -> *V1StorefrontUsers
- delivery-promise-notification: {put,patch}DeliveryPromisesExternalSellers*
-> {put,patch}ApiDeliveryPromisesExternalSellers*
Removed tools (endpoints no longer in upstream schemas):
- VTEX_GET_ROLES_BY_USER2 (getRolesbyUser2) — alternate endpoint dropped;
VTEX_GET_ROLES_BY_USER (getRolesbyUser) remains.
- VTEX_ORDER_CHANGES_POST_CHANGE (postOrderChanges) — removed from the
pick-and-pack-order-changes schema.
Prereq for enabling zod metadata (param descriptions): doing that regen on
top of a current client yields a description-only diff. Build is warning-free;
all 104 tests pass. metadata stays false here (no bundle change).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Flips `metadata: false` -> `true` in openapi-ts.config.ts and regenerates.
The generated Zod request schemas now carry field descriptions, which flow
through the tool adapter into each tool's inputSchema — i.e. the JSON Schema
sent to the LLM. Previously every param (e.g. orders `f_RnB`) reached the
agent as a bare `string` with no meaning or value-format hint.
Stacked on the client-sync PR, so this diff is metadata-only: sdk.gen.ts and
types.gen.ts are byte-identical to the base; only zod.gen.ts files change
(field lines reflow to add `.register(z.globalRegistry, { description })`).
Cost (measured): server bundle 4.70 -> 6.05 MB raw, 629 -> 944 KB gzipped
(+301 KB / +47%) — inherent, the description strings must ship to reach the
LLM. Truncating to 120 chars saved only ~34 KB gzip while cutting the
value-format examples, so descriptions are kept full.
Adds a guard test so `metadata: false` can't silently return. All tests pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Generated Zod schemas are produced with `metadata: false`, so no field description reaches the tool inputSchema (the JSON Schema the LLM sees). Agents got bare `f_RnB: string` with no hint of meaning or value format — which is why an agent couldn't map a coupon/promotion query to `f_RnB`. Rather than re-enabling metadata globally (measured: +1.57 MB / +35% server bundle, plus unrelated upstream schema drift and a broken export on regen), layer curated descriptions onto the flattened input schema in the tool adapter. Covers the params where the omission hurts on VTEX_LIST_ORDERS (f_RnB, date ranges, status, full-text q), written richer than the raw OpenAPI text — e.g. f_RnB now explains the coupon -> promotion-id lookup. Bundle unchanged (4.70 MB). Adds regression tests asserting descriptions reach the agent-facing JSON Schema and that overrides keep fields optional. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
guitavano
changed the title
This was referenced Jul 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Single PR covering the whole fix. Supersedes #523, #524 (now closed).
Problem
An agent on the VTEX MCP couldn't tell it needed
f_RnBto count sales for a coupon/promotion (e.g.FICA10/ "Pop retenção DECO"). Root cause: the agent received no description for any parameter of any tool. The generated Zod schemas were built withmetadata: false(comment: "descriptions are not read at runtime" — inaccurate for an MCP: the input schema becomes the JSON Schema sent to the LLM). Everyf_filter reached the agent as a barestring.The global fix
One line —
metadata: false→trueinopenapi-ts.config.ts— then regenerate. This turns on descriptions for every field of every tool at once. The*.gen.tschanges are generator output (bun run openapi), not hand edits.What's in this PR (3 commits)
chore: regenerate client from current upstream— the committed client had drifted; regenerating surfaced 8 renamed/removed operations. Reconcilesregistry.ts(6 renames; removesVTEX_GET_ROLES_BY_USER2andVTEX_ORDER_CHANGES_POST_CHANGE, whose endpoints no longer exist upstream). Doing the sync first keeps the metadata step a clean, description-only diff. (Only hand edit:registry.ts.)feat: enable Zod metadata— flips the flag + regenerates.sdk.gen.ts/types.gen.tsare byte-identical to commit 1; onlyzod.gen.tsfiles change (fields reflow to add.register(z.globalRegistry, { description })). (Only hand edit: 1 line in the config.)fix: curated param descriptions— layers richer-than-OpenAPI text on the params where VTEX's own wording is jargon (adapter-level,param-descriptions.ts). Notablyf_RnBnow explains it takes the promotion id, not the coupon code, and thatFICA10/ a promotion name must be resolved via the promotions tools first.Why the diff is huge but the review surface is tiny
registry.ts..register()reflows every described field across 13.7k fields. No operation/schema change — proven by sdk/types being byte-identical.Cost (measured)
Server bundle 4.70 → 6.05 MB raw, 629 → 944 KB gzipped (+301 KB / +47%). Inherent — description strings must ship to reach the LLM. Truncating to 120 chars saved only ~34 KB gzip while cutting the value-format examples, so descriptions are kept full.
Verification
z.toJSONSchema:f_RnB/f_statusdescriptions land in the agent-facing schema; the curatedf_RnBtext wins over the raw generated one.metadata: falsecan't silently return.🤖 Generated with Claude Code