Skip to main content
Glama
screener-mcp
by LogeshR15

ask_company_research

Read-only

Ask questions across a company's annual reports and earnings-call transcripts to retrieve relevant excerpts with document and page citations; narrow by document type, year, quarter, or PDF.

Instructions

Ask a question over a company's annual reports and earnings-call transcripts using semantic search — across all recent documents at once, one document type, or a single document.

ask_company_research("TCS", "How has capex strategy evolved?") # 3 ARs + 4 calls ask_company_research("ITC", "Key regulatory risks", doc_type="annual_report") ask_company_research("TCS", "Key risks", year=2024) # one annual report ask_company_research("HDFCBANK", "NIM guidance", quarter="Q3FY25") # one earnings call

Downloads and indexes the PDFs locally on first use (cached after that), then returns the most relevant excerpts (each capped to ~900 characters, with document and page) — BRSR/sustainability boilerplate is ranked down unless the question is about ESG.

doc_type: "all" | "annual_report" | "earnings_call" year: one annual report (e.g. 2024) — implies doc_type="annual_report" quarter: one earnings call (e.g. "Q1FY26") — implies doc_type="earnings_call" pdf_url: search this PDF directly (label it with year or quarter) max_annual_reports / max_earnings_calls: how many recent documents to include when no year/quarter is given force_reindex: re-download and rebuild the index (see each document's freshness.source_changed)

Requires the [ai] extra: pip install 'screener-mcp[ai]'

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "symbol": "<symbol>"
    },
    "name": "ask_company_research"
  }
}

Input Schema

NameRequiredDescriptionDefault
yearNo
symbolYes
pdf_urlNo
quarterNo
doc_typeNoall
questionNo
force_reindexNo
max_annual_reportsNo
max_earnings_callsNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.6.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only say readOnlyHint and openWorldHint, but the description discloses the real operational traits: PDFs are downloaded and indexed locally on first use and cached afterward, results are excerpts capped near 900 characters with document and page, and BRSR/sustainability boilerplate is down-ranked unless the query is ESG-related. It also flags a hard dependency ('Requires the [ai] extra'), which annotations cannot express.

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?

Front-loaded with the core statement, then examples, then a compact parameter glossary, so an agent can stop reading early. The parameter block restates some scoping rules already demonstrated in the examples, which is slight redundancy but arguably useful for disambiguation.

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?

For a 9-parameter search tool with an output schema available, the description covers scope selection, indexing/caching cost, result shape and ranking behavior, and the installation prerequisite. Nothing an agent needs to invoke it correctly or predict latency is absent.

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

Parameters5/5

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

Schema description coverage is 0%, so the description carries the full burden, and it does: doc_type enumerates the three valid values, year and quarter are documented with their side effect of implying doc_type, pdf_url explains direct-PDF search, and the two max_* params explain recency windowing. Only symbol and question are left self-evident by name.

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 in the first clause: 'Ask a question over a company's annual reports and earnings-call transcripts using semantic search'. It also distinguishes scope variants (all docs vs one doc_type vs single document), so an agent can tell it apart from sibling lookup tools like get_document_list or search_company.

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?

Four concrete call examples show exactly which argument selects which search scope, and the parameter notes reinforce the implied doc_type behavior of year/quarter. What's missing is any explicit when-not guidance or a named alternative (e.g. when to prefer search_market_commentary or get_document_list instead).

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