Twenty-two tools on the VecViz agent API

The subscriber-facing MCP server at /mcp, one tool per /v1 REST twin. Every tool is read-only except report_feedback, every one is priced from the request alone so an agent knows the cost before it calls, and every one refuses an unknown ticker rather than silently dropping it. Costs below were executed against the live rate card, not read off the docstrings.

Endpoint: POST /mcpagents-vecviz.fly.dev
Transport: statelessStreamable HTTP; no Mcp-Session-Id, so the app runs multiple workers
Auth: Beareror X-VecViz-Key, for clients that cannot prepend a scheme
Tools: 2221 read-only, 1 write (feedback)
Zero-cost: 5catalog, methodology, usage, feedback, model_review
Unit: 1 tickerone ticker’s analytics at one model date

How the surface behaves

Seven conventions hold across every tool. They are the things that surprise a first integration.

Price is knowable in advance

Every pricing rule reads only the request — never the response or the database. meta.units reports what was charged and meta.units_basis shows the arithmetic. A quoted price is always an upper bound: skip_unknown is the only thing coverage can affect, and it only lowers the charge.

Refusals are not billed

An unknown ticker (400), any other 4xx, and all 5xx are free. Units are reserved before the call runs and refunded if it does not bill, so a failed call costs nothing.

as_of detects a refresh

Pass the as_of token from a prior response and a dataset refresh between calls returns 409 rather than silently mixing model dates. The token is the newest mtime across all datasets, so it moves when any of them does.

Coverage is validated, not priced

Three datasets back the surface and they genuinely disagree on membership, so each tool validates against its own coverage set. Validation never affects the price — that would make cost depend on something the caller cannot see.

Strict symbols

An unrecognised ticker is refused, not dropped. Call vecviz_catalog first — it is free precisely so an agent never spends quota to learn what is current. Names come and go between refreshes.

Three tools bill under another name

The published tool name is not always the billed one. vecviz_catalog and model_review bill to the methodology bucket — which is how they are free — and vna_scenario bills and validates coverage as vna_whatif. Pricing by the published name gives the wrong rule for all three.

Everything returns text

Tools return an MCP text block wrapping a JSON envelope: data plus meta (request id, latency, units, as_of, warnings). Partial results are reported in meta.warnings rather than thrown away.

All twenty-two, at a glance

Filter by name, job, or parameter. Costs are units; the rate card treats one unit as one ticker’s analytics at one model date.

Tool	Does	Cost	Job

Every tool in detail

Parameters are exactly what the published MCP schema exposes. The internal _request shim is stripped from every signature, so it never appears to a caller. Required parameters are marked.

What things actually cost

Each row was priced by calling the surface’s own rate_card.price(), so these are the numbers that will be billed — not a paraphrase of the tool descriptions.

Call	Rule	Units	Why