fix(catalog): demonstrate * 1000 Date conversion in time-series exampleCalls

[Aliiiu]

Closes #39

Summary

Fixes the classic Unix-seconds-vs-ms JS Date trap that surfaced in the latest Aiden Phase-3 Q3 evidence: model called the historical-TVL endpoint, did new Date(p.date) (no * 1000), got 1970-01-XX, burned ~54s in retry/recover loops on the formatting, and ultimately returned a degraded answer.

Root cause is upstream-shape, not a model bug: DefiLlama returns date as Unix seconds on the /v2-style series endpoints, while JS new Date(n) expects milliseconds. Verified live:

$ curl https://api.llama.fi/v2/historicalChainTvl/Ethereum
# last entry: { "date": 1782172800, "tvl": 37970061149 }
# new Date(1782172800 * 1000) → 2026-06-23T00:00:00.000Z  ✓
# new Date(1782172800)        → 1970-01-21T15:02:52.800Z  ✗  (the failure mode)

What changed

Same lever as PR #15 / #16 / #20 / #26 / #28 — the exampleCall is the contract surfaced to the model via search_docs. Update the three /v2-style time-series endpoints' projections to demonstrate the conversion inline:

Endpoint	New projection
getHistoricalChainTvl	date: new Date(p.date * 1000).toISOString() /* p.date is Unix seconds; multiply by 1000 for JS Date */
getStablecoinCharts	same pattern, with totalCirculatingUSD
getStablecoinPrices	same pattern, with prices

The fourth time-series endpoint (getHistoricalPoolData) is different — HistoricalPoolItemSchema declares timestamp: z.string() (already ISO from yields.llama.fi), so it does not need the * 1000. Added an inline comment there so the model doesn't apply the pattern by mistake:

timestamp: p.timestamp /* already an ISO string, unlike the date:number fields on /v2 endpoints */

Deliberately scoped out

• No instructions.md change. A generic "Unix-seconds vs ms" hint would be cheat-sheet territory. The right surface is the per-endpoint exampleCall demonstrating the right idiom (matches the same minimal-instruction approach the prior PRs used).
• No type-layer fix. Latent issue from PR fix(catalog): shape responses inside execute(); guide narrow-vs-broad #28 — ProtocolData declares tvl: number but /protocol/{slug} returns tvl: array. Still out of scope; tracked separately.

Test plan

• pnpm exec tsc --noEmit clean
• pnpm test → 171 passed
• Regenerated embedded-index.ts (ships the new exampleCall to search_docs consumers)
• Verified live against https://api.llama.fi/v2/historicalChainTvl/Ethereum that the * 1000 conversion is the right idiom for this endpoint
• Post-merge: confirm a fresh Aiden Phase-3 Q3 run no longer hits the 1970-01-XX failure mode or burns time in date-formatting retry loops

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request fixes a JS Date issue in the exampleCall definitions for several time-series endpoints (getHistoricalChainTvl, getStablecoinCharts, and getStablecoinPrices) by multiplying the Unix seconds timestamp by 1000 before converting it to an ISO string. It also adds an explanatory comment to getHistoricalPoolData where the timestamp is already formatted as an ISO string. These updates are applied to both tool-metadata.ts and embedded-index.ts. There are no review comments, and the changes look correct, so I have no feedback to provide.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.