Skip to main content
Glama
Public Company Reporting Window Finder

Public Company Reporting Window Finder

Build Company Universe

build_company_universe
Idempotent

Build a filtered list of public companies by exchange, country, sector, float, fiscal year end, cadence, and status. Use it for targeted reporting-window and investor outreach.

Instructions

Build a list of listed companies from filters rather than from identifiers you already hold. Filter by exchange, country, region, sector, security type, public float band, fiscal year end month, reporting cadence, operating status and foreign private issuer status. Returns 44 fields per company, the same shape resolve_company returns. At least one filter is required, so a bare call cannot pull the whole universe. This tool does NOT accept company identifiers: use resolve_company, qualify_company or get_reporting_timing for specific companies. SET limit EXPLICITLY. It defaults to 1000 and you are charged per company row returned, so an unbounded call is an expensive call. Truncation is always reported, never silent. Requires an APIFY_TOKEN and consumes Apify credits. Read only.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "build_company_universe"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum rows for universe and season. Truncation is always reported, never silent.
regionsNoShorthand for a set of venues and countries: us, uk, eu. Widens an explicit exchange or country filter rather than replacing it.
sectorsNoSEC SIC descriptions, e.g. Pharmaceutical Preparations. Populated on roughly 65 percent of the publishable universe.
cadencesNoquarterly, semiannual, annual, unknown.
country_codesNoISO 3166-1 alpha-2, e.g. US, GB, FR.
exchange_codesNoISO 10383 MICs. 18 venues are covered.
security_typesNoordinary_shares, depositary_receipt, preferred_shares.
public_float_bandsNomicro, small, mid, large, mega, unknown. Size runs on public float because market capitalization is not populated anywhere in this dataset.
us_registrant_onlyNoKeep only companies carrying an SEC CIK.
exclude_share_alikeNoDrop rows derived from CC BY-SA sources, whose share alike condition may not suit a closed product.
exclude_blank_checksNoDrop pre deal SPACs. Separate from the operating company filter: a blank check shell is flagged as an operating company and passes every ordinary firmographic filter.
fiscal_year_end_monthsNoIntegers 1 to 12. Fiscal year end is effectively a United States field in this dataset.
foreign_private_issuerNoFilter on foreign private issuer status.
operating_companies_onlyNoDrop funds, trusts and other non operating entities. Sent as a string for Clay compatibility.
exclude_name_only_matchesNoDrop rows whose identity link rests on a name and country agreeing rather than on an identifier. Use this wherever a wrong identity link matters.
min_provenance_confidenceNoSet to high to exclude rows whose source terms were never read.
exclude_december_fiscal_year_endNoKeep only companies whose fiscal year ends in a month other than December, the accounts whose budget cycle is out of phase with a calendar quarter.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.1.2
    • removedInput schema / additionalProperties
      Removed value: -false
  2. First observedv1.0.0

TDQS

A4/5.0
Behavior1/5

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

The description ends with 'Read only', but annotations declare readOnlyHint=false, a direct contradiction of the structured safety hint. Although the description otherwise discloses valuable behavior (Apify token requirement, per-row credit cost, limit default of 1000, reported truncation), the explicit read-only claim against a readOnlyHint=false annotation is a serious inconsistency that an agent would rely on incorrectly.

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 purpose, then exclusions, then the at-least-one-filter rule, then the cost warning, then the token/auth note. Dense but each sentence carries a distinct operational fact; only the closing 'Read only' is wasted (and harmful) given the rest of the payload.

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 17-parameter filter tool with no output schema, the description supplies the missing return-value context ('44 fields per company, the same shape resolve_company returns'), the cost and truncation model, the auth requirement, and the identifier exclusion. Nothing an agent needs to call it correctly is absent.

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 100%, so the baseline is 3; however the description adds the limit default (1000) and the per-row billing model, neither of which appear in the schema text, and enumerates the filter families so the agent knows what dimension each parameter targets. It adds real meaning over the schema rather than repeating it.

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 (build a list of listed companies) and immediately scopes it against identifier-based lookup, explicitly naming siblings resolve_company, qualify_company and get_reporting_timing as the tools to use for specific companies. An agent can distinguish it from every sibling without opening a schema.

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?

Explicit when-to-use (derive a universe from filters), when-not-to-use (you already hold identifiers, or want specific companies), and hard operational rules: at least one filter is required, and limit must be set explicitly. Also warns it does NOT accept company identifiers, which is the key selection trap against the sibling tools.

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