• 1. the message is human-readable
• 2. the free_tools field is named explicitly
• 3. the upgrade_url carries a UTM tag
• 4. the _pro_only_tool field underscores intent
• what’s free vs what’s gated
• what a successful free call looks like for contrast
• the upgrade decision an agent should make
• install

the v0.3.2 release shipped a specific design choice. when a free-tier key calls a gated tool, the response is not a generic 402 page. it is a structured JSON envelope that an installed agent will surface verbatim in its own answer.

this post is what that envelope actually looks like, why the fields are shaped the way they are, and how the design changes the upgrade decision for an agent loop.

i tested it earlier today. here is the literal response from calling confluence_today on a free-tier key:

{ "error": "pro_feature", "message": "'confluence' is a Pro feature. Free tier: top_yield_farms / hl_vault_leaderboard / macro_tape. Upgrade $19/mo to unlock all 13 tools. https://falsifylab.com/pro?ref=tool-gate", "upgrade_url": "https://falsifylab.com/pro?ref=tool-gate", "free_tools": ["top_yield_farms", "hl_vault_leaderboard", "macro_tape"], "_pro_only_tool": "confluence" }four things to notice.

§1. the message is human-readable

the message field is not a status code. it is a sentence the LLM running your agent will quote when it has to explain to you why the tool returned no data. it names the three free tools the user still has access to. it names the price. it gives the upgrade URL.

this is a different design than a 402 status with no body. with no body, the agent reports “the tool failed” and the user has to figure out why. with this body, the agent reports “the tool is Pro-only, you can use these three free ones instead, or upgrade for $19/mo”.

the second answer continues the workflow. the first answer kills it.

§2. the free_tools field is named explicitly

free_tools is an array. an agent reading the response can re-route the user’s original question to a free tool that approximates the answer. for the example call (confluence_today), the closest free tool is none of them, because cross-source confluence has no free analog. but for a hypothetical Pro-gated specialized signal, an agent could fall back to a free related tool and add a one-line explanation that the gated version would be more precise.

agents that handle this well degrade gracefully. agents that fail this lose the user.

§3. the upgrade_url carries a UTM tag

?ref=tool-gate is the UTM source param. it is different from the UTMs the marketing copy uses (?ref=substack-v032, ?ref=x-thread, and so on). this isolates conversion attribution. a Pro signup from the tool-gate UTM means the conversion path was “user installed the MCP, hit a wall, clicked through”. a Pro signup from a substack UTM means the conversion path was “user read a blog post, then went to checkout”.

the two paths have different conversion rates and different funnel costs. measuring them separately matters because the next product decision depends on which path actually converts.

§4. the _pro_only_tool field underscores intent

the underscore prefix marks it as machine-only metadata. agents that want to log which tool tripped the gate can use this field directly without parsing the message string. it is a small affordance but it makes downstream telemetry cleaner.

§what’s free vs what’s gated

free tier returns 5 results per query, 60 requests per hour, 24h cache lag:

• top_yield_farms returns DeFi yield farms with realistic APY (emissions stripped)

• hl_vault_leaderboard returns Hyperliquid vaults ranked by NAV, 30d return, max drawdown

• macro_tape returns the live US macro snapshot covering equity indices, vol, rates, FX, commodities, BTC, ETH

Pro at $19/mo unlocks the other 10: insider Form 4 clusters, material 8-K filings, ETF flow today, polymarket whale positions, active airdrop farms, on-chain smart wallets, plus the 3 radars added in v0.3.2 (earnings drift, token unlocks, fed comm), plus the differentiator confluence_today.

§what a successful free call looks like for contrast

calling macro_tape on the free tier returns the live snapshot:

{ "count": 20, "items": [ {"key": "SPX", "last": 7473.47, "pct_1d": 0.88, "pct_5d": 0.95}, {"key": "VIX", "last": 16.7, "pct_1d": -6.29}, {"key": "UST10", "last": 4.558, "pct_1d": -1.41}, {"key": "WTI", "last": 97.0, "pct_1d": -10.73}, {"key": "BTC", "last": 75563.67, "pct_1d": -1.55}, {"key": "ETH", "last": 2069.0, "pct_1d": -1.94} ] }real data, real timestamps. the free tier is enough to confirm the system is alive and the data is fresh. the gate only fires when the call is for a tool that requires Pro-tier compute or proprietary aggregation.

§the upgrade decision an agent should make

the decision is not “is the gate annoying enough that i pay to remove it”. the decision is “is the gated tool load-bearing in my agent loop”.

if your agent loop calls confluence_today every iteration and the answer changes whether the agent acts, the tool is load-bearing. the upgrade math is straightforward at $19 per month.

if your agent loop is research-only and 24-hour-old free-tier data is sufficient for the question you are answering, the upgrade math does not work. the free tier is the right tier.

the gate forces this question into the workflow. that is the design.

§install

pip install falsifylab-alpha-mcp==0.3.2add to your MCP client config. restart. the MCP loads. no key needed for free tier.

falsifylab.com/pro

research and educational content only. not investment, legal, or tax advice. do your own research.

#OnchainAlpha #BTCFlow #ETHFlow

Originally published on FalsifyLab Substack.