Skip to main content
Glama
tearsheet

tearsheet

by kewonit

read_filing

Read-only

Read a filing from the filings folder: choose PDF pages or retrieve XBRL results with company, period, basis, and crore figures, including multi-period data for financial analysis.

Instructions

Read part of one filing from the filings folder.

    Give a file name as search_filings returns it. For a PDF, pages picks a
    page or range such as "4" or "4-6", up to ten pages. For an XBRL
    results filing, returns the company, period and basis, and its figures
    with money in crore and each figure's own period, because a filing for
    a second quarter also holds half-year figures. Breakdowns are left out.
    Only files inside the filings folder can be read.
    

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": {
      "file": "<file>"
    },
    "name": "read_filing"
  }
}

Input Schema

NameRequiredDescriptionDefault
fileYes
pagesNo1-3

Output Schema

NameRequiredDescriptionDefault
dataYes
as_ofNo
unitsNo
entityNo
sourcesNo
warningsNo
next_cursorNo
retrieved_atNo
verificationNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.1/5.0
Behavior4/5

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

Annotations only declare readOnlyHint, so the description carries the rest and does add real behavior: page ranges capped at ten pages, XBRL results returning company/period/basis plus per-figure periods in crore, and breakdowns being omitted. It does not describe pagination/truncation beyond the ten-page cap or what happens if a file is missing or outside the folder.

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?

Purpose is front-loaded, then parameter form, then return shape, then the folder restriction. Every sentence carries content, though the XBRL return paragraph overlaps with the available output schema and could be tighter.

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 two-parameter read tool with an output schema and a readOnly annotation, the agent gets purpose, input format, page semantics, file-type-dependent returns and a scope restriction. Nothing essential for a correct call 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?

With 0% schema description coverage, the description compensates well: 'file' means a name in the form search_filings returns, and 'pages' takes a single page or a range like "4" or "4-6" with a ten-page ceiling, and applies only to PDFs. The default value 1-3 is left to the schema and the string format edge cases are not spelled out, so it falls short of full coverage.

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 and resource ('Read part of one filing from the filings folder') plus a clear handoff to the sibling that produces the input ('Give a file name as search_filings returns it'). It stops short of an explicit read-vs-search routing statement, so it is clear but sibling differentiation is only implied.

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?

Establishes the precondition (a file name exactly as search_filings returns it) and a hard constraint ('Only files inside the filings folder can be read'). It also conditions behavior on file type (PDF vs XBRL), but never says when not to use it or which sibling to use for other needs.

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