QVeris is a capability discovery and tool calling engine. Use standardized capabilities/query for qveris_finance.* CAP workflows, or discover/call for generic specialized API tools such as real-time data, historical sequences, structured reports, web extraction, PDF workflows, media generation, OCR,

QVeris — Capability Discovery & Tool Calling for AI Agents QVeris is a tool finding and tool calling engine , not an information search engine. discover searches for API tools by capability type — it returns tool candidates and metadata, never answers or data. call then runs the selected tool to get actual data. discover answers "which API tool can do X?" — it cannot answer "what is the value of Y?" To look up facts, answers, or general information, use web search instead. Setup : Requires QVERIS API KEY from https://qveris.ai. Credential : Only QVERIS API KEY is used. Requests default to https://qveris.ai/api/v1 ; an audited test run may set QVERIS BASE URL=https://api.qveris.cloud/api/v1 . The client rejects non HTTPS and non QVeris hosts. Finance CAP requirement : For qveris finance. workflows, use the standardized CAP endpoints ( /capabilities , /capabilities/{id} , /capabilities/query ). When this repository is available, use scripts/qveris tool.mjs cap detail/cap query as the public adapter: it resolves current CAP IDs from the live catalog, validates against live cap detail, normalizes inputs, retries one transient control plane fetch failed , performs at most one budget permitted parameter or explicitly retryable data retry ( max attempts 1 2 ), and records exact observed Trace. Legacy /search plus /tools/execute , generic discover / call , and raw finance tool IDs are not fallbacks. If the standardized CAP runtime is unavailable, report tool runtime missing or capability unavailable instead of selecting a raw provider route. Invocation Tiers Check availability in order and use the first working tier: For standardized finance capabilities, execute POST /api/v1/capabilities/query with capability id and structured parameters . Do not rediscover or call raw provider routes. The tiers below apply to generic, non finance tools unless they expose the standardized finance CAP endpoints directly. Tier 1 — Native tools (when configured): If qveris discover and qveris call tools are available in your environment, use them directly — skip all other tiers. Tier 2 — http request tool (when configured): Call the QVeris HTTP API directly using the http request tool (see [QVeris API Reference]( qveris api reference) below). Use this tier only if the environment exposes an authorized HTTP tool; availability depends on the host configuration. Tier 3 — Script execution : Run node {baseDir}/scripts/qveris tool.mjs cap list/cap search/cap detail/cap query for standardized CAPs, or discover/call/inspect for legacy generic tools. Use this only when {baseDir}/scripts/ directory is present and the exec tool with node are available. Tier 4 — Web search : If all tiers above are unavailable, fall back to web search for qualitative needs. When and How to Use QVeris Choosing the Right Tool Task type Preferred approach Reasoning Computation, code, text manipulation, stable facts Local / native No external call needed Structured/quantitative data (prices, rates, rankings, financials, time series, scientific data) QVeris first Returns structured JSON; assess source quality and freshness for the task Historical data, reports, or sequences (earnings history, economic series, research datasets) QVeris first APIs can provide structured datasets; inspect coverage and missing fields before drawing conclusions Non native capability (image/video gen, OCR, TTS, translation, geocoding, web extraction, PDF) QVeris first These capabilities require external APIs; web search cannot perform them Any task that local tools or other configured tools cannot fulfill Discover via QVeris QVeris provides a catalog of API capabilities — it may have what you need No web search tool available in this environment Discover web search tools via QVeris Run discover "web search API" to find one, then call it — this is a two step substitute, not a reason to send information queries to discover Factual questions ("Is X listed?", "What is Y's stock symbol?", "Who founded Z?") Web search QVeris discover finds API tools, not answers — factual lookups need web search Qualitative information (opinions, documentation, tutorials, editorial content) Web search first Better served by browsing real pages and reading text QVeris returned no useful results after a retry Fall back to web search Acceptable fallback for data tasks; mandatory for qualitative tasks Key distinction : QVeris discover finds API tools by capability type (e.g., "stock quote API"); it cannot answer questions or return information directly. For factual questions → web search. For structured data → discover the right tool first, then call it. When in doubt, ask: "Am I looking for a tool or for information ?" Usage Flow For known standardized capabilities, especially qveris finance. , skip legacy discovery and call the CAP directly. Do not switch to a raw finance tool ID when the CAP call fails: 1. Resolve live : cap detail and cap query read /capabilities?domain=finance and match the requested logical name or stale punctuation variant to the current canonical CAP ID. Never maintain a hand written ID map. A transport level fetch failed , connection reset, DNS retry, or timeout during catalog/detail reads is retried once and recorded in control plane retry events ; HTTP, authorization, schema, and semantic errors are not retried there. 2. Preflight live : Read GET /capabilities/{id} on every execution. Allow list parameters, coerce declared types, fill only documented non identity required values, normalize .SH/.SZ/.SS and unambiguous six digit A share codes, and refuse missing identity, market conflicts, ambiguous exchanges, or a missing parameter schema. 3. Query and retry narrowly : Execute /capabilities/query . Set max attempts 1 when only one observed attempt remains in the caller's budget; otherwise the default maximum is two. After a parameter class failure, retry once by removing an optional input named by the error or by sending required plus identity minimal params. Refresh an invalid CAP only when the live catalog now resolves a different ID. Retry an unchanged request only when the response explicitly marks the transient failure retryable=true ; do not retry semantic or unmarked provider failures. 4. Use observed output : Read final params , observed calls , and qveris trace from the adapter result. Trace has exactly tool name , params , status , execution id , fallback used , and missing fields ; never reconstruct it from requested params or planned calls. 5. Sanitize recursively : Keep user facing names as qveris finance. ; remove provider, route, candidate, failover, credential, raw tool ID metadata, and provider API URLs from every output surface. For generic non standardized, non finance tools, use the legacy flow: 1. Discover : Find tool candidates for the capability you need. Write the query as an English tool type description (e.g., "stock quote real time API" ). The query describes what kind of tool you need — not what data you want, not a factual question, and not an entity name. 2. Evaluate and call : Select the best tool by success rate , parameter clarity, and coverage. Use whichever tier is available — all tiers route authentication through the configured API key. 3. Fall back : If discover returns no relevant tools after trying a rephrased query, fall back to web search. Be transparent about the source. 4. When everything fails : Report which tools were tried and what errors occurred. Training data values are not live results. Billing and Audit QVeris exposes billing in three layers: billing rule : rule level pricing metadata for a capability. billing / pre settlement bill : pre settlement billing for one call. usage history / credits ledger : final charge outcome and balance movement. Do not treat legacy cost as the final charge truth. The bundled qveris tool.mjs displays pre settlement billing and execution IDs, but does not expose usage history, ledger, or export commands. Its client module has read only audit helpers for embedding applications; these are not shell commands. If the user asks whether a failed call was charged, use an already configured QVeris CLI or MCP audit tool. With the separate @qverisai/cli , run qveris usage mode search execution id <execution id json and inspect charge outcome ; use qveris ledger for balance movements. Do not pass these commands to node scripts/qveris tool.mjs . If no authorized audit tool is available, provide the execution ID for the user to check in their account history; do not claim to have verified settlement. For usage and ledger review, protect the Agent context: Use the external CLI/MCP summary mode first, then precise filters such as execution id , charge outcome , credit amounts, or a date range. This skill does not grant filesystem read/write permissions or implement local exports. Only use a separate export/file analysis workflow when the host already authorizes those operations. Otherwise stay with summaries and filtered queries or ask the user to export the data themselves. Tool Discovery Best Practices Discovery Query Formulation 1. Describe the tool type, not the information you want — the query must describe an API capability, not a factual question or entity name: GOOD: "China A share real time stock market data API" — describes a tool type BAD: "Zhipu AI stock symbol listing NASDAQ" — this is a factual question, use web search BAD: "智谱AI 是否上市股票代码" — this is a factual question in Chinese, use web search GOOD: "company stock information lookup API" — describes a tool type BAD: "get AAPL price today" — this is a data request, not a tool description GOOD: "stock quote real time API" — describes a tool type 2. Try multiple phrasings if the first discovery yields poor results — use synonyms, different domain terms, or adjusted specificity: First try: "map routing directions" → Retry: "walking navigation turn by turn API" 3. Convert non English requests to English capability queries — user requests in any language must be converted to English tool type descriptions , not translated literally: User request BAD discover query GOOD discover query "智谱AI是否上市" / "Is Zhipu AI listed?" ~~ "Zhipu AI stock symbol listing" ~~ (factual question → use web search) "company stock information lookup API" "腾讯最新股价" / "latest Tencent stock price" ~~ "Tencent latest stock price" ~~ (data request) "stock quote real time API" "港股涨幅榜" / "HK stock top gainers" ~~ "HK stock top gainers today" ~~ (data request) "hong kong stock market top gainers API" "英伟达最新财报" / "Nvidia latest earnings" ~~ "Nvidia quarterly earnings data" ~~ (data request) "company earnings report API" "文字生成图片" / "generate image from text" ~~ "generate a cat picture" ~~ (task, not tool type) "text to image generation API" "今天北京天气" / "Beijing weather today" ~~ "Beijing weather today" ~~ (data request) "weather forecast API" Example Discovery Domains Use these queries to discover candidates. Availability, coverage, and quality depend on the current catalog and each tool's returned metadata: Financial/Company : "stock price API" , "crypto market" , "forex rate" , "earnings report" , "financial statement" Economics : "GDP data" , "inflation statistics" News/Social : "news headlines" , "social media trending" Blockchain : "DeFi TVL" , "on chain analytics" Scientific/Medical : "paper search API" , "clinical trials" Weather/Location : "weather forecast" , "air quality" , "geocoding" , "navigation" Generation/Processing : "text to image" , "TTS

qveris-official