How do I use finanal-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@finanal-mcp Explain the macro and narrative behind NVDA's rally." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

finanal-mcp

by Sekharz

Overview Schema Source Related Servers Discussions Admin

Python

Remote

finanal-mcp

A minimal, token-efficient MCP server that combines stock prices and fundamentals with the macro and micro narrative around them — so an AI agent can reason about why a stock moved, what people are thinking about it, and what probable scenarios lie ahead.

Why this project exists

Knowing a stock's PE ratio or current price is not enough. The interesting questions are: why did this stock dip today? What does the market narrative say about it? What are the macro tailwinds or headwinds? What could happen next?

Answering those questions requires combining three things simultaneously:

Fundamentals and price data — earnings, ratios, revenue growth, institutional flows
Real-time news and macro context — what analysts, media, and macro events are saying
The narrative — sentiment, concall tone, sector rotation, management guidance

The tools chosen — FMP, Tapetide, and Tavily — are the best available for each of those jobs. FMP is the gold standard for US stock fundamentals. Tapetide is purpose-built for Indian NSE/BSE data with native MCP support. Tavily is a research-grade search engine that retrieves and synthesises real-time financial news.

Why not use the existing MCP servers for these tools directly?

All three providers publish their own MCP servers, but each exposes 50–100+ individual tools. Every tool description gets embedded into the system prompt of every LLM call. With three servers active that's potentially 150–300 tool descriptions injected into every single prompt — input tokens explode, costs spike, and the LLM gets confused by the noise.

This project is the solution: one MCP server, 6 tools maximum. The LLM talks to a single router that knows which underlying API to call, how to call it, and what parameters to use. The input token footprint stays flat no matter how many endpoints exist in the index.

finanal-mcp in one sentence: ask any financial question in plain English — the server finds the right API, calls it, and caches the answer for instant reuse.

Related MCP server: financial-research-agent

Why it is built this way

Decision	Rationale
6 tools maximum	Each tool description is injected into every LLM prompt. Keeping the count to 6 keeps the input token footprint minimal and constant (~159 tokens total), regardless of how many underlying endpoints are indexed.
Slim `search_apis` responses	`search_apis` returns only `id, source, path, summary, score` (~310 tokens for 10 results). Full schema is deferred to `get_api_details`, only called when the right endpoint is identified. Before this, full rows cost ~1,232 tokens per search call.
Response field trimming in `call_api`	Known-verbose fields (`description`, `cik`, `cusip`, `isin`, `address`, `phone`, `image`) are stripped from FMP responses. Cuts a typical `/profile` response from ~360 to ~149 tokens — the LLM never needed the 3-paragraph company bio.
SQLite + FTS5 BM25 instead of vector embeddings	The endpoint index is ~300 rows. BM25 + finance synonyms hits ~90% accuracy with zero extra dependencies and zero latency. Vector search adds complexity and a model inference call for no measurable gain at this scale.
Finance synonym expansion baked into `db.py`	"PE ratio", "price to earnings", "valuation multiple" are the same query. Expanding tokens before FTS search avoids the most common failure modes without needing an LLM call.
Tapetide as a proxied MCP server instead of a direct REST client	Tapetide exposes a native MCP server at `https://mcp.tapetide.com/mcp`. Proxying it over JSON-RPC means we never need to maintain an OpenAPI spec for 49+ Indian market tools — they stay current automatically.
Tavily for news instead of FMP news endpoints	FMP's news APIs require a paid plan (return HTTP 402 on free tier). Tavily's search engine covers US/global news, macro events, and earnings headlines on the free tier with far richer synthesis.
Recipe cache as the first tool call	BM25 is fast but not perfect. Recipes are exact-match quality. Any question answered once correctly is answered instantly forever after, with zero redundant API discovery. A recipe hit skips both `search_apis` and `get_api_details` — the two most expensive steps.
uv for all Python	Reproducible builds, fast installs, no system Python pollution. All commands use `uv run`.

Source routing rules

These rules are enforced both in the search_apis tool description and in seeded recipes, so any LLM using this server learns them from the first call.

Source	Use for	Never use for
tapetide	Indian NSE/BSE: quotes, news, fundamentals, shareholding, FII/DII, screener, concalls	US or global stocks
fmp	US and global stocks: price, financials, earnings, analyst estimates, SEC filings	News (paywalled, returns 402)
tavily	All news and macro: US stock news, Fed/RBI decisions, earnings headlines, any web search	N/A — use as fallback for anything news-shaped

Why not just use prompt caching?

A fair question: FMP, Tapetide, and Tavily each publish their own MCP servers. If you registered all three directly, the LLM would have the full tool list in its context. And since modern LLMs (Claude, GPT-4o) cache the system prompt, subsequent calls would hit the cache at ~90% discount — so it would barely cost anything after the first call, right?

Prompt caching fixes the wallet problem. This architecture fixes the brain problem. Even with perfect cache hits, monolithic tool registrations still fail in three ways:

1. Cache eviction tax (TTL ~5–10 minutes)

Prompt caches are ephemeral. Most providers evict after 5–10 minutes of inactivity. If a user pauses to read, grabs a coffee, or writes a long reply — the cache evicts. The very next turn re-indexes all 150–300 tool schemas at 1.25× the base rate (cache-write premium), and the full cost resets. With 6 tools and ~159 tokens of descriptions, a cache eviction costs fractions of a cent. The TTL problem simply disappears.

2. Model attention tax ("lost in the middle")

Even if holding 200,000 tokens of tool schemas in context is cheap, it is not free for the model's reasoning. When an LLM has to parse 500 tool schemas simultaneously its retrieval accuracy degrades measurably — it hallucinates optional parameters, confuses endpoints with similar names, and dilutes attention on the actual task. By routing through search_apis first, the model only sees the 3–4 tools it actually needs for that specific turn. Attention stays sharp.

3. Context window starvation

Every model has a hard context limit. If 200,000 tokens are permanently occupied by monolithic tool schemas, that is 200,000 fewer tokens available for conversation history, API response payloads, and deep reasoning. For a tool-heavy financial workflow where API responses can be large, this matters.

The compounding win: recipes

The deeper lever is the recipe cache. A recipe hit means the model calls exactly one tool (search_recipes) instead of the usual three (search_recipes → search_apis → get_api_details → call_api). Every question answered correctly makes the next identical question instant and near-zero cost. The system gets cheaper and more accurate over time.

Measured token budget

Component	Tokens
All 6 tool descriptions combined	~159
`search_apis` response, 10 results (slim)	~310
`search_apis` response, 10 results (old, full rows)	~1,232
FMP `/profile` response, trimmed	~149
FMP `/profile` response, untrimmed	~360
A typical recipe hit (skips search entirely)	~80

Architecture

Copilot / LLM agent
        │
        ▼
  finanal-mcp (stdio)
  ┌─────────────────────────────────────────────┐
  │  search_recipes  ← check cache first        │
  │  search_apis     ← BM25 + synonym index     │
  │  get_api_details ← full schema for endpoint │
  │  search_docs     ← BM25 doc search          │
  │  call_api        ← live API call            │
  │  save_recipe     ← cache successful answer  │
  └──────────────┬──────────────────────────────┘
                 │  routes by source field
       ┌─────────┼──────────┐
       ▼         ▼          ▼
    FMP REST  Tavily REST  Tapetide MCP
    (US/global) (news)     (India NSE/BSE)

Prerequisites

Python ≥ 3.14
uv — brew install uv or pip install uv
API keys for FMP, Tavily, and Tapetide (free tiers available for all three)

Setup

git clone <repo>
cd finanal
uv sync
cp .env.example .env
# Edit .env and fill in your three API keys

Get your keys:

FMP: https://site.financialmodelingprep.com/developer/docs — free tier, 250 req/day
Tavily: https://app.tavily.com — free tier, 1,000 credits/month
Tapetide: https://tapetide.com/mcp — free token from settings

Seed the endpoint index

Run once after cloning (or after pulling updates):

uv run scripts/seed_fmp_scrape.py   # 236 FMP endpoints from official docs
uv run scripts/seed_tavily.py       # 7 Tavily endpoints
uv run scripts/seed_tapetide.py     # 49 Tapetide tool schemas
uv run scripts/enrich_docs.py       # 348 synthetic BM25 docs

Verify with smoke tests

uv run scripts/test_search.py
# Expected: 15/15 ✓ all rank-1

Run the MCP server

uv run python main.py

The server communicates over stdio and is consumed by VS Code / Copilot via the MCP protocol. You do not interact with it directly.

Register in VS Code (user-level — works in all workspaces)

Add to ~/Library/Application Support/Code/User/mcp.json (macOS) or the equivalent user-level mcp.json on your OS:

{
  "servers": {
    "finanal-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "/absolute/path/to/finanal"
    },
    "tapetide-mcp": {
      "type": "http",
      "url": "https://mcp.tapetide.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TAPETIDE_TOKEN",
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

Note: tapetide-mcp is registered separately as an HTTP server so Copilot can call its tools directly (faster path). finanal-mcp proxies through to it as well, but direct registration gives Copilot access to all 49 Tapetide tools without going through the router.

How to use it from Copilot Chat

finanal-mcp is a tool router, not a chat assistant. An LLM agent (Copilot, Claude, etc.) calls its tools to discover and invoke the right financial API. The mandatory workflow:

Step-by-step tool call order

1. search_recipes(query)
   └─ If score < -1.0 → use that recipe directly, skip to call_api. Done.

2. search_apis(query, source="fmp"|"tapetide"|"tavily")
   └─ Returns ranked endpoint list with id, summary, source, parameters.

3. get_api_details(endpoint_id)
   └─ Returns full parameter schema so call_api gets the right args.

4. call_api(endpoint_id, params={...})
   └─ Executes the live API call and returns the data.

5. save_recipe(question, summary, endpoint_ids=[...])
   └─ Always save after a good answer — next identical query is instant.

Example queries and what happens

Query	Route	Tool sequence
"Polycab current price"	tapetide	search_recipes → call_api(tapetide get_stock_quote)
"VRT Vertiv stock price"	fmp	search_recipes → call_api(fmp /profile)
"Polycab latest news"	tapetide	search_recipes → call_api(tapetide get_stock_news)
"Vertiv news 2026"	tavily	search_recipes → call_api(tavily /search, topic=finance)
"RELIANCE PE ratio"	fmp	search_recipes → search_apis → call_api(fmp /ratios)
"India FII DII flows today"	tapetide	search_recipes → call_api(tapetide get_fii_dii_flows)
"US Fed rate decision news"	tavily	search_recipes → call_api(tavily /search, topic=news)

Teaching the server new routing rules

Seed recipes directly:

import db
conn = db.get_conn()
db.upsert_recipe(
    conn,
    question="Get quarterly earnings for an Indian company",
    summary="Use tapetide get_financials (source=tapetide), section='profit_loss'.",
    endpoint_ids=[22],
)
conn.commit()

Or use the save_recipe tool from within a Copilot chat session after a successful answer.

DB state (after full seed)

Source	Endpoints	Notes
fmp	236	Scraped from official FMP docs + community OpenAPI YAML
tapetide	49	Tapetide native MCP tool schemas
tavily	7	Hand-crafted from Tavily OpenAPI spec
Total	292
Docs (BM25)	348	Synthetic per-endpoint + per-tag-group docs
Recipes	6+	Seeded routing rules; grows with use

Key files

main.py                      ← FastMCP server — 6 tools, source-aware call_api routing
db.py                        ← SQLite schema, FTS5 tables, BM25 search, synonym expansion
scripts/seed_fmp_scrape.py   ← Primary FMP seed (236 endpoints from scraped docs)
scripts/seed_fmp.py          ← Secondary FMP seed (community OpenAPI YAML, 181 endpoints)
scripts/seed_tavily.py       ← Tavily endpoint seed
scripts/seed_tapetide.py     ← Tapetide tool schema seed
scripts/enrich_docs.py       ← Synthetic BM25 doc generation (348 docs)
scripts/test_search.py       ← Smoke tests (15/15 expected)
specs/tavily.yaml            ← Hand-crafted Tavily OpenAPI spec
data/finanal.db              ← SQLite database (gitignored)
.env.example                 ← API key template
.github/copilot-instructions.md ← Copilot tool workflow instructions

Available Tools

6 tools

call_apiB

Call a live API endpoint by endpoint_id and params.

ParametersJSON Schema

Name	Required	Description	Default
`params`	No
`endpoint_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description must disclose behavioral traits. It only says 'call a live API endpoint', but does not specify if it's idempotent, has side effects, requires authentication, or what happens on error. This is insufficient for safe usage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, front-loaded with the action and key arguments. No filler words; every word serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, the return value is documented elsewhere. However, the description lacks details on error behavior, rate limits, or how the 'live' call fits into the workflow. It is adequate but not complete for a production tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning no parameter descriptions in the schema. The description merely restates the parameter names ('endpoint_id' and 'params') without explaining their semantics, expected formats, or constraints. For example, 'params' is an object with no structure hints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Call' and the resource 'API endpoint', and lists the two parameters by name. It distinguishes from siblings like search_apis and get_api_details, which are about finding or inspecting APIs, not executing them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, such as using search_apis first to find endpoint_id. No prerequisites, limitations, or caveats are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_api_detailsB

Get full metadata/schema for an endpoint by id.

ParametersJSON Schema

Name	Required	Description	Default
`endpoint_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It only states the action without disclosing read-only nature, auth requirements, rate limits, or response details beyond what an output schema might imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that immediately states the purpose. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has one required parameter and an output schema, the description is functional but lacks context about how to obtain the endpoint_id (e.g., from search_apis). It is minimally adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description only mentions 'by id', not explaining the endpoint_id parameter's origin or meaning. The description minimally compensates for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states what the tool does: get full metadata/schema for an endpoint by ID. It is a specific verb+resource and distinguishes itself from siblings like search_apis or call_api.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, such as search_apis to find an endpoint first. No exclusions or context for when to apply it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

save_recipeC

Save a solved recipe to cache.

ParametersJSON Schema

Name	Required	Description	Default
`doc_ids`	No
`summary`	Yes
`question`	Yes
`endpoint_ids`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

C2.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description states 'save to cache' implying a write operation, but lacks details on side effects (e.g., overwriting existing entries), persistence guarantees, or error conditions. With no annotations, this is insufficient for understanding behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short (one sentence), but conciseness comes at the cost of missing essential details. It is front-loaded with the action but omits necessary clarifications.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With four parameters, no parameter descriptions, no annotations, and an output schema present but unaddressed, the description is critically incomplete. The agent cannot determine which parameters are required or how they are used.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description provides no explanation for any of the four parameters (doc_ids, summary, question, endpoint_ids). Given 0% schema description coverage, the description adds no value beyond the parameter names themselves.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Save') and resource ('solved recipe') indicating the action. However, it does not clarify what constitutes a 'solved recipe' or how this tool differs from sibling tools like 'search_recipes' or 'call_api'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool, prerequisites, or alternatives. The description does not mention when not to use it or how it fits into a workflow.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_apisA

Search API endpoints across fmp, tapetide, and tavily. Source routing: tapetide=India NSE/BSE, fmp=US/global stocks, tavily=all news. Pass source='tapetide'|'fmp'|'tavily' to restrict. Returns slim rows (id, source, path, summary, score) — call get_api_details for full schema.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	Yes
`source`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description carries full burden. It discloses that search spans three APIs, returns slim rows with specified fields, and points to another tool for details. Implies read-only search behavior. Missing rate limits or auth but acceptable for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences packed with essential info: main action, source routing, output format, and cross-reference. No redundant words, perfectly front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Describes inputs, behavior, output, and alternative tool. Missing details like pagination/ordering and query behavior, but output schema exists and overall coverage is good for a search tool with multiple sources.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must add meaning. It explains the source parameter options and their routing. For limit and query, no extra information beyond schema defaults. Adds value for source but not comprehensive for all parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it searches API endpoints across three named sources (fmp, tapetide, tavily). Distinguishes from sibling get_api_details by specifying it returns slim rows and delegates full schema retrieval. Verb+resource is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains source routing (tapetide=India, fmp=US/global, tavily=news) and instructs to pass source parameter to restrict. Advises to call get_api_details for full schema, providing an alternative. Does not explicitly state when not to use, but context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_docsC

Search synthetic/ingested docs with BM25.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description mentions BM25, adding some algorithmic transparency. However, it omits critical details like read-only nature, result format, ordering, and case sensitivity, which are especially important given the absence of annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (one sentence). While it avoids waste, it sacrifices necessary detail about parameters and usage, making it too terse for effective agent guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low tool complexity (2 params, no nested objects) and presence of an output schema, the description is barely sufficient for selection but fails to provide input parameter details needed for correct invocation. Usage context and behavioral details are missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, and the tool description does not explain either parameter (query or limit). An agent must infer semantics solely from parameter names and default values, which is insufficient for reliable invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Search') and resource ('synthetic/ingested docs') with method ('BM25'), distinguishing it from sibling search tools like search_apis and search_recipes. However, it does not specify the nature of the documents beyond 'synthetic/ingested'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives such as search_apis or search_recipes. The description provides no context for appropriate usage scenarios or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_recipesA

Search previously solved Q&A recipes. ALWAYS call this FIRST before search_apis or call_api. If a matching recipe exists (score < -1.0 is a strong match), return it directly without further API calls.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses search behavior and matching threshold but does not mention read-only nature, no side effects, or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words; front-loads purpose and crucial usage instruction. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having output schema, description could briefly summarize key output fields (e.g., recipe IDs and scores) to aid result interpretation. However, ordering and threshold info make it largely complete for its role.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%. Description only implies 'query' purpose but does not explain parameter format, role, or the 'limit' parameter at all, failing to compensate for schema gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches previously solved Q&A recipes, distinguished from siblings like search_apis by ordering instruction and matching threshold.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises 'ALWAYS call this FIRST before search_apis or call_api' and specifies when to return directly (score < -1.0 strong match), providing clear when-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

6 tool updatesv0.1.0Jul 11, 2026
- First observedcall_api
- First observedget_api_details
- First observedsave_recipe
- First observedsearch_apis
- First observedsearch_docs
- First observedsearch_recipes

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0

Scored 2026-07-11 12:25 across 6 tools

Disambiguation5/5

Each tool has a clear, distinct purpose: call_api vs get_api_details separate invocation from metadata, search tools target different data types (APIs, docs, recipes), and save_recipe is uniquely for caching solved queries. No ambiguity between tools.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with snake_case: call_api, get_api_details, save_recipe, search_apis, search_docs, search_recipes. No mixed conventions.

Tool Count5/5

6 tools is ideal for a server that provides search, details, and invocation across multiple data sources. Each tool earns its place without being overly narrow or broad.

Completeness4/5

The set covers the full workflow: search for APIs, get details, call them, search docs, and reuse saved recipes. Minor gap: no explicit tool to list all endpoints or manage recipes beyond saving, but core functionality is complete.

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Drillr — The financial MCP for AI agents A
ai.drillr
The financial MCP for AI agents - 90+ financial tables, SEC filings, signals, alt-data.
Finance Research & Data Data Platforms
1036
ko-mcp A
io.github.SharpLu
Real SEC, 13F, insider, congress & macro data your AI agent can cite. Hosted MCP, 24 tools.
Finance Government Data
242
china-market-intelligence-mcpOAuth
com.thenextgennexus
MCP server giving AI agents one-connection access to China A-share market intelligence: financials,
Finance Research & Data
2
Ultralayer B
io.github.UltralayerHQ
Realtime financial context for AI agents: what changed, who is affected, and what to watch next. One suite covering news, events, guidance, filing changes, sentiment, stakeholders, and alerts. Information-efficient responses with evidence for every result. First-class point-in-time safety for backtests. Pairs well with web search and a market-data API. All data is our own.
Finance Research & Data
1911

Related MCP Servers

OpenInsider MCP
Finance Research & Data
btopn
A
license
Not graded
quality
A
maintenance
An MCP server that exposes 16 free investment-research signals (insider trades, SEC filings, short data, and live quotes) to any MCP-compatible LLM.
Updated a month ago (2026-08-07 15:13 UTC)
36
98
MIT
financial-research-agent
Finance AI & Machine Learning
rahul-jajala
F
license
Not graded
quality
D
maintenance
MCP server that exposes stock research tools (fundamentals, news, technicals, analyst ratings) to AI clients, enabling autonomous generation of structured investment briefs.
Updated 3 months ago (2026-06-09 22:20 UTC)
-
openmarkets
Finance Cryptocurrency
danchev
A
license
B
quality
B
maintenance
A Model Context Protocol (MCP) server for agentic retrieval of financial data from Yahoo Finance, enabling stock information, historical data, analyst data, and more.
Updated 4 days ago (2026-09-09 13:19 UTC)
71
3
AGPL 3.0
Stock Analyzer MCP
Finance Research & Data
codewithadvi
F
license
Not graded
quality
D
maintenance
Production-grade MCP server that enables AI assistants to access real-time financial market data with intelligent fallback mechanisms, supporting stock prices, comparisons, fundamentals, and market summaries via Yahoo Finance and CSV.
Updated 8 months ago (2026-01-03 19:10 UTC)
-