Skip to main content
Glama
psxdata

psxdata-mcp

by psxdata

psxdata-mcp

An MCP server that gives AI assistants Pakistan Stock Exchange data. It runs locally in Docker: the assistant loads PSX data (prices, screener, index constituents, sectors, filings, debt market, margin-eligible scrips) into a private in-memory DuckDB and answers your questions with SQL. It's built on psxdata.

Requires: Docker, except for the Claude Desktop one-click bundle (see below), which needs uv instead.

Install

Install in VS Code

Claude Code (plugin, recommended):

claude plugin marketplace add psxdata/psxdata-mcp
claude plugin install psxdata@psxdata-mcp

Claude Code (plugin, hosted server: invite-only, no Docker, adds warehouse marts):

claude plugin marketplace add psxdata/psxdata-mcp
claude plugin install psxdata-hosted@psxdata-mcp

Claude Code asks for the server URL when the plugin is enabled; use the one from your invitation. Then run /mcp and sign in to psxdata. Install one of the two plugins, not both.

Claude Code (server only):

claude mcp add --transport stdio --scope user psxdata -- docker run -i --rm -v psxdata-cache:/home/app/.psxdata mtauha/psxdata-mcp:latest

Cursor: open this link: cursor://anysphere.cursor-deeplink/mcp/install?name=psxdata&config=eyJjb21tYW5kIjoiZG9ja2VyIiwiYXJncyI6WyJydW4iLCItaSIsIi0tcm0iLCItdiIsInBzeGRhdGEtY2FjaGU6L2hvbWUvYXBwLy5wc3hkYXRhIiwibXRhdWhhL3BzeGRhdGEtbWNwOmxhdGVzdCJdfQ==

Claude Desktop (one-click): download psxdata-mcp-<version>.mcpb from the latest release and open it (or drag it into Settings → Extensions). This route needs no Docker, but it runs on uv, which it uses to fetch Python and the dependencies on first launch; install uv first if Claude Desktop reports it missing. The first launch takes a few seconds longer than later ones.

Any other client: add to its MCP config (Claude Desktop's is claude_desktop_config.json):

{
  "mcpServers": {
    "psxdata": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "psxdata-cache:/home/app/.psxdata", "mtauha/psxdata-mcp:latest"]
    }
  }
}

Related MCP server: psx-mcp

Tools

Tool

What it does

load_prices(symbols, start?, end?)

Daily OHLCV for up to 50 symbols → prices

load_screener()

All ~729 symbols with price, P/E, dividend yield, market cap → screener

load_index(name)

Constituents and weights of KSE100, KSE30, KMI30, … → index_constituents

load_sectors()

37-sector summary → sectors

load_fundamentals(symbols?)

Filed financial reports list → fundamentals

load_symbols()

All listed symbols with name and sector → symbols

load_debt_market()

TFCs, Sukuks, government securities → debt_market

load_eligible_scrips()

Margin-eligible scrips by market → eligible_scrips

query(sql)

DuckDB SQL over loaded tables (≤200 rows, 30 s, no file/network access)

list_tables()

What's loaded, row counts, load time

quote(symbol)

Latest snapshot for one symbol

Ask things like "How has OGDC done against KSE-100 constituents this year?" or "Which cement stocks have a P/E under 6?"

Skills

Ready-made analysis workflows, served as MCP prompts (pick them from your client's prompt menu, e.g. /mcp__psxdata__tearsheet in Claude Code) and shipped as skills in the Claude Code plugin, which Claude loads on its own when a request matches.

Skill

What it does

psx-playbook

The rules every analysis follows: data traps, SQL patterns, web cross-checks

tearsheet(symbol)

One-page report on a stock: performance, risk, valuation vs. sector, filings, news

screen(criteria?)

Value, dividend or momentum presets, or your own conditions, with red flags

shariah-screen(screen?)

The same screens limited to KMI All-Share members, with purification notes

compare(symbols, period?)

2–10 stocks side by side: returns, risk, correlation, valuation, price path

market-wrap(period?)

Daily or weekly summary: KSE-100 drivers, breadth, sectors, movers, news

Sources live in src/psxdata_mcp/skills/*.md; skills/ is generated from them with uv run python scripts/sync_skills.py (a test fails if the two drift).

Good to know

  • Prices are PKR and not adjusted for splits, bonus issues or dividends.

  • Historical data is cached in the psxdata-cache Docker volume, so each symbol is downloaded once. Live data (screener, sectors, quotes) refreshes every 15 minutes.

  • Loaded tables live in memory and reset when the assistant session ends.

  • Data is scraped from the public PSX website; it isn't an official feed.

Development

uv sync
uv run pytest                    # unit + server tests
uv run pytest -m live            # hits real PSX
docker build -t psxdata-mcp:dev . && uv run pytest -m container
uv run python scripts/stage_mcpb.py build/mcpb      # stage the Claude Desktop bundle
npx @anthropic-ai/mcpb pack build/mcpb build/psxdata-mcp.mcpb
PSXDATA_MCP_BUNDLE=build/psxdata-mcp.mcpb uv run pytest -m bundle
npx @modelcontextprotocol/inspector docker run -i --rm psxdata-mcp:dev

License

MIT

Available Tools

11 tools
list_tablesA

List loaded tables with row counts and load time (UTC). No columns — use query("DESCRIBE ") for those.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

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

No annotations are present, so the description carries the burden; a 'List' verb plus the disclosure of exactly what is returned (row counts, load time normalized to UTC) makes the read-only, non-mutating nature unambiguous. It stops short of stating pagination or freshness behavior, but for a zero-parameter listing tool the behavioral surface is thin.

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 short sentences, zero filler. The primary behavior is front-loaded and the fallback pointer follows immediately.

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

Completeness5/5

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

An output schema exists and covers the return values, so the description need not restate them; the description is nonetheless complete about scope, timezone, and the boundary with query. Nothing an agent needs to call this correctly is missing.

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

Parameters4/5

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

The tool takes no parameters, so there is nothing to disambiguate and no description burden. The description's mention of the timezone for load time is useful framing rather than a parameter claim.

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?

States a specific verb+resource ('List loaded tables') and specifies the returned fields (row counts, load time in UTC). It also carves out scope against the sibling query tool by noting it does not return columns.

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?

Explicitly states the exclusion ('No columns') and routes the agent to the alternative ('use query("DESCRIBE <table>")'), which is clear context for choosing between the two. It doesn't cover when to prefer it over the load_* siblings, but those are ingestion rather than inspection tools.

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

load_debt_marketB

Load PSX debt instruments (TFCs, Sukuks, government securities: face value, dates, coupon rate, maturity) into table debt_market, one category per instrument group.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior3/5

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

With no annotations, the description carries the full behavioral burden. It does disclose useful behavior — what fields are ingested, the destination table, and the 'one `category` per instrument group' grouping semantic — but says nothing about write semantics (insert vs. upsert/replace), permissions, network/data-source requirements, or expected runtime for an ingestion job.

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

Conciseness4/5

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

A single dense sentence that front-loads the action, the instrument types, and the destination table. The parenthetical field list is informative rather than filler, though the sentence packs enough clauses that it could be split for readability.

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?

An output schema exists, so return values need no explanation, and with zero parameters there is nothing to document on input. The description covers what is loaded and where, but leaves ingestion preconditions (data source, credentials, overwrite behavior) unstated, which is the only meaningful gap.

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

Parameters4/5

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the schema to document and nothing the description needs to disambiguate. The parenthetical list of loaded fields is descriptive context rather than parameter explanation.

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?

States a specific verb ('Load') and a precise resource (PSX debt instruments: TFCs, Sukuks, government securities) plus the destination table `debt_market`. The debt-instrument scope cleanly separates it from sibling loaders like load_prices or load_fundamentals, though the description never names those siblings explicitly.

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?

The description is purely declarative about what gets loaded; it gives no when-to-use condition, no prerequisites (e.g. auth or data source availability), and no guidance on when to prefer it over `query`, `list_tables`, or other load_* tools. The agent must infer its role from the name alone.

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

load_eligible_scripsB

Load margin-trading eligible scrips by market category into table eligible_scrips.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/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 for what is plainly a write/ingest operation. It says data lands in eligible_scrips but not whether it replaces or appends to existing rows, whether it is idempotent, or what auth/rate constraints apply.

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

Conciseness4/5

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

A single front-loaded sentence with no filler; the destination table is stated up front. It is appropriately sized for a no-argument ingestion tool.

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?

An output schema exists, so return values need not be described, and with zero parameters the schema side is trivially complete. What is missing for a table-writing tool is the write semantics (overwrite vs append) and any safety context, which the absent annotations leave fully on the description.

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

Parameters4/5

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description's reference to 'market category' could mislead an agent into looking for a filter that does not exist, but no parameter meaning is left unclear.

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?

States a specific verb (Load) and resource (margin-trading eligible scrips) plus the destination table, which distinguishes it from the other load_* siblings that target different data domains. The phrase 'by market category' is slightly ambiguous given there is no category parameter.

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 run this versus load_screener, load_symbols, or the other load_* tools, and no indication of prerequisites or whether it should be run before/after related loads. The agent must infer usage entirely from the name.

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

load_fundamentalsA

Load the list of filed financial reports (year, type, period, posting date, document link) into table fundamentals. Not valuation metrics — those are in screener. Omit symbols to load all filings.

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior3/5

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

No annotations are provided, so the description carries the behavioral burden. It discloses the payload shape and the 'omit symbols = load all filings' scoping behavior, which is useful, but it never states whether loading replaces or appends to the `fundamentals` table, what permissions/network access are needed, or whether the operation is reversible.

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 tight sentences, front-loaded with the primary action and destination table, followed by the sibling exclusion and the default-scope note. No filler; each sentence carries distinct information.

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?

An output schema exists, so return values need no explanation, and the description covers target table, loaded fields, and default scoping for a single-parameter tool. The main residual gap is the write semantics (overwrite vs append) that an agent populating a table would want to know.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must compensate, and it does handle the single parameter well: 'Omit symbols to load all filings' explains that symbols is an optional filter whose absence broadens scope to everything. It does not specify the expected symbol format, but the semantics of the one parameter are otherwise clear.

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?

States a specific verb (load) plus the resource (filed financial reports) and the exact target table, even enumerating the loaded columns (year, type, period, posting date, document link). It explicitly distinguishes itself from the sibling load_screener, so an agent can route without opening either schema.

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?

It clarifies when the tool is NOT appropriate ('Not valuation metrics — those are in `screener`') and documents the default behavior when symbols is omitted. Clear routing context, though it does not address the other loading siblings (load_prices, load_index) or any prerequisites for repeated loads.

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

load_indexA

Load constituents and weights of a PSX index (e.g. KSE100, KSE30, KMI30) into table index_constituents. Re-loading an index replaces only that index's rows.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior3/5

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

With no annotations, the description carries the full behavioral burden, and it does disclose the key mutation trait: re-loading replaces only that index's rows (idempotent per-index refresh). It says nothing about data source, network/auth requirements, whether other indices are touched, or failure behavior, leaving meaningful gaps for a write operation.

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, zero waste, with the core action and destination table front-loaded before the re-load caveat. Every clause earns its place.

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?

An output schema exists, so return values need not be explained, and the description covers the action, destination, and upsert semantics. For a single-parameter mutation tool with no annotations, an extra note on data source or error behavior would round it out.

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

Parameters4/5

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

Schema description coverage is 0% for the single `name` parameter, so the description must compensate — and it does, by enumerating valid index identifiers (KSE100, KSE30, KMI30), which effectively defines the parameter domain. It still does not state format expectations (case sensitivity, whether aliases work), so it is strong but not complete.

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?

States a specific verb (Load) and resource (constituents and weights of a PSX index) and names the destination table `index_constituents`, with concrete examples (KSE100, KSE30, KMI30) that pin down what an 'index' is. It does not explicitly distinguish itself from siblings like load_prices or load_sectors, but the resource is distinct enough to be inferred.

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

Usage Guidelines3/5

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

The description implies use (populating the `index_constituents` table) and clearly states re-load semantics, but never says when to call it versus siblings such as load_symbols or load_screener, nor any prerequisites. Usage is inferable from the resource name rather than stated.

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

load_pricesA

Load daily OHLCV prices (PKR, unadjusted) for up to 50 PSX symbols into table prices.

Omit start/end for the full history. Re-loading a symbol replaces all its rows.

ParametersJSON Schema
NameRequiredDescriptionDefault
endNo
startNo
symbolsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior4/5

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

With no annotations, the description carries the full load and does well: it discloses the currency (PKR), that prices are unadjusted, the 50-symbol cap, the full-history default, and the destructive semantics of re-loading (all rows for that symbol are replaced). It omits auth/permission requirements and error handling for invalid symbols, so it falls short of a 5.

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 short sentences, front-loaded with what is loaded and where, then the date default, then the replacement caveat. No filler and every sentence carries distinct information.

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?

An output schema exists, so return values need no explanation, and the description covers the critical call-shaping facts: limit, currency, adjustment basis, date defaulting, and destructive replacement. What is missing is edge-case behavior (unknown symbols, partial failure), which keeps it below 5.

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

Parameters4/5

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

Schema coverage is 0%, so the description must compensate, and it does: it defines start/end behavior (omit for full history) and characterizes symbols (up to 50 PSX tickers). It leaves date format and inclusive/exclusive range bounds unspecified, but the core meaning of all three parameters is conveyed.

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?

States a specific verb (load) plus resource (daily OHLCV prices, PKR, unadjusted) and destination table `prices`, which naturally separates it from load_index, load_sectors, and load_fundamentals. It never names a sibling explicitly, so the routing is inferred rather than stated.

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

Usage Guidelines3/5

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

It gives one genuine usage rule ('Omit start/end for the full history') and an implicit constraint (max 50 symbols), which is more than nothing. But it never says when to load vs. when to use query or quote, nor does it warn about re-loading symbols whose data is already present.

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

load_screenerA

Load the full PSX screener (~729 symbols: sector, price, market cap, P/E, dividend yield, free float, 30-day avg volume, 1-year change) into table screener. 15-min snapshot.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It usefully discloses the destination table, the ~729-symbol scope, and the 15-minute snapshot cadence, which is real behavioral context. But it does not say whether existing rows are overwritten, whether auth is required, or how the load is triggered, leaving notable gaps for a write-shaped loader.

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, front-loaded with the action and destination, followed by the field inventory and freshness note. No filler, no redundancy.

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?

For a zero-parameter loader with an output schema, the description covers contents, destination table, and data freshness. The main missing piece is whether the load replaces or appends to table `screener`, and that gap is minor given the annotations-free, simple shape.

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

Parameters4/5

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

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond what the empty schema already shows. Baseline 4 applies; the field list describes data content rather than parameters, which is helpful but not strictly required.

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?

Specific verb (Load) plus resource (the full PSX screener) and destination (table `screener`), with a concrete field list that tells the agent exactly what data lands where. It does not differentiate itself from overlapping siblings such as load_fundamentals or load_prices, which cover some of the same fields, so it falls short of 5.

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

Usage Guidelines3/5

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

Usage is implied: the ~729-symbol breadth and field list make it clear this is the broad market snapshot tool, and '15-min snapshot' hints at freshness expectations. However, there is no explicit when-to-use versus load_fundamentals/load_prices, and no stated prerequisites or exclusions.

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

load_sectorsA

Load the PSX sector summary (advances, declines, turnover, market cap for all 37 sectors) into table sectors. 15-min snapshot.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the write destination (table `sectors`), the row scope (all 37 sectors), and the freshness cadence (15-minute snapshot), but says nothing about whether existing rows are replaced or appended, whether the load is idempotent, or what access it needs.

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 short sentences, zero filler, and the most important information (what is loaded and where it lands) is front-loaded. The parenthetical field list and cadence both earn their place.

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?

Because an output schema exists, return values need not be described. For a no-parameter ingestion tool the description covers scope, destination, and freshness; only the overwrite/replace semantics of the load are left unstated.

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

Parameters4/5

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

The tool takes zero parameters, so the schema is empty and the description has nothing to disambiguate. Baseline 4 applies; the mention of 'all 37 sectors' usefully confirms there is no filtering capability rather than leaving the agent to infer it.

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?

Specific verb (Load) plus a precisely scoped resource (PSX sector summary: advances, declines, turnover, market cap for all 37 sectors) and the destination table `sectors`. An agent immediately knows what the tool produces, but nothing in the text distinguishes it from siblings like load_index or load_prices.

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 statement of when to pick this over load_index, load_prices, or load_screener, nor any prerequisites. The only usage-adjacent signal is the '15-min snapshot' cadence, which hints at refresh frequency but does not tell the agent when this tool is the right choice.

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

load_symbolsB

Load all listed PSX symbols with company name, sector and ETF/debt/GEM flags into table symbols.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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 behavioral burden. It implies a write operation by saying data is loaded 'into table `symbols`', but does not disclose whether existing rows are replaced, whether the load is idempotent, permissions required, or any rate limits/side effects.

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, front-loaded sentence with no filler. It communicates the operation, the data fields, and the destination table without any redundant phrasing.

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?

An output schema exists, so return values need not be described. However, with no annotations and no usage guidance, the description leaves behavioral questions unanswered — notably whether this load mutates/replaces existing symbol data and when it should be used relative to sibling loaders.

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

Parameters4/5

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

The tool takes zero parameters, so there is no parameter semantics to document. Per the rubric, zero parameters sets the baseline at 4, and the description does not need to explain anything further about arguments.

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 states a specific verb ('Load') and resource ('listed PSX symbols'), and names the fields loaded (company name, sector, ETF/debt/GEM flags) plus the destination table (`symbols`). It is clearly distinguishable from siblings like load_prices or load_fundamentals, though it does not explicitly name an alternative tool.

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?

The description says what is loaded but gives no guidance on when to use this tool versus sibling loaders such as load_sectors or load_eligible_scrips. There are no conditions, prerequisites, or exclusions stated, so the agent must infer usage entirely.

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

queryA

Run DuckDB SQL over the loaded tables. Returns at most 200 rows as a table; aggregate or LIMIT for large results. You may create views/tables. No file or network access.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

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

No annotations are supplied, so the description carries the full burden and does well: it discloses the 200-row result cap, that DDL (creating views/tables) is permitted, and that file and network access are blocked. It stops short of describing error behavior or whether truncation is silent versus flagged.

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 short sentences, front-loaded with the core action, and every clause earns its place by communicating a capability or constraint. No filler.

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

Completeness5/5

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

An output schema exists, so return values need not be described, and the one thing the agent most needs to know instead — the 200-row cap — is stated. Capabilities, sandbox limits, and the dialect are all covered, making the definition complete for a one-parameter execution tool.

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

Parameters4/5

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

The single 'sql' parameter has 0% schema description coverage, so the description must compensate. It does so by naming the dialect (DuckDB SQL) and the sandbox constraints that bound what SQL is valid (no file/network, DDL allowed), which is meaningfully more than the bare schema provides.

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?

States a specific verb and resource: run DuckDB SQL over the loaded tables. The scope ('over the loaded tables', the 200-row cap, sandbox restrictions) distinguishes it cleanly from the sibling load_* tools and from list_tables/quote without needing the schema.

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

Usage Guidelines3/5

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

It gives usage advice ('aggregate or LIMIT for large results') which tells the agent how to work within the row cap, but never states when to reach for query versus siblings such as list_tables or quote, nor any prerequisites (e.g. that tables must be loaded first).

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

quoteA

Get the latest snapshot for one PSX symbol (price, sector, market cap, P/E, dividend yield, 1-year change). Does not create a table.

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. 'Does not create a table' does disclose the absence of a persistent side effect on the table catalog, but it says nothing about read-only guarantees, auth requirements, or rate limits.

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

Conciseness4/5

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

Two tight sentences with the core purpose front-loaded and the field list immediately following. The trailing 'Does not create a table' is slightly oblique but does earn its place as a disambiguation hint.

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?

An output schema exists, so return values need no explanation, and a single required parameter keeps the surface small. The only real gap is the absence of a symbol format example (e.g., a ticker like 'OGDC').

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% (the lone 'Symbol' field has no description), so the description is the only source of meaning. It clarifies the parameter is a single PSX ticker, which adds value, but supplies no format or example.

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?

States a concrete verb+resource ('Get the latest snapshot for one PSX symbol') and enumerates the returned fields (price, sector, market cap, P/E, dividend yield, 1-year change). This clearly distinguishes it from table-materializing siblings like load_prices and load_fundamentals, though it never names an alternative directly.

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

Usage Guidelines3/5

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

'Does not create a table' implicitly signals this is a lightweight point lookup rather than a load_* materialization, which is useful routing context. However, there is no explicit when-to-use vs. when-to-use-a-sibling statement or exclusion 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.

  1. 11 tool updatesv0.1.0
    • First observedlist_tables
    • First observedload_debt_market
    • First observedload_eligible_scrips
    • First observedload_fundamentals
    • First observedload_index
    • First observedload_prices
    • First observedload_screener
    • First observedload_sectors
    • First observedload_symbols
    • First observedquery
    • First observedquote

TDQS

A3.8/5.0

Scored across 11 tools

Disambiguation5/5

Each tool loads a distinct dataset or performs a distinct operation (prices, screener, index, sectors, fundamentals, symbols, debt, eligible scrips, query, list_tables, quote). Overlap between load_screener and quote is resolved by scope (all symbols vs single symbol) and table creation behavior. load_fundamentals explicitly clarifies it excludes valuation metrics, avoiding confusion with load_screener.

Naming Consistency4/5

All names use snake_case, which is consistent. However, eight tools follow a load_<noun> (verb_noun) pattern, while query and quote deviate (just verb and noun), making the pattern not perfectly uniform.

Tool Count5/5

11 tools are appropriate for the breadth of PSX data categories, each loading a distinct table or providing a distinct query utility. No tool appears redundant, and the count is well within the sweet spot of 3-15.

Completeness4/5

The surface covers key market data: prices, snapshots, indices, sectors, symbols, debt, and filings. However, it lacks tools for deeper fundamental data (e.g., financial statement line items) and time-series index values, which are notable gaps for advanced analysis.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    D
    maintenance
    Enables AI assistants and IDEs to execute SQL queries on local DuckDB databases, in-memory databases, or cloud-stored databases with support for flexible connections and configurable result limits.
    1
    1
    MIT
  • A
    license
    A
    quality
    C
    maintenance
    MCP server that exposes Pakistan Stock Exchange data (quotes, dividends, announcements, indices) as LLM-callable tools, enabling conversational market queries in plain English.
    9
    29 PyPI
    4
    MIT
  • F
    license
    Not graded
    quality
    D
    maintenance
    Enables querying Pakistan Stock Exchange data including market summaries, stock quotes, history, and sector breakdowns using natural language.
    -
  • A
    license
    A
    quality
    C
    maintenance
    Provides live Pakistan Stock Exchange data including quotes, intraday and end-of-day history, indices, company fundamentals, dividends, and announcements via the Model Context Protocol, with no API key required.
    10
    1
    MIT