Skip to main content
Glama
mambalabsdev

Public Company Reporting Window Finder

by mambalabsdev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Get Reporting Timing

get_reporting_timing
Idempotent

Predict a public company's next reporting date and compute the open and close of a defined outreach window around it.

Instructions

Find when a public company next reports, and when to reach out around it. Returns 75 fields per input: fiscal year end, derived reporting cadence and its confidence, the next reporting event with its type, period and date, days to event, and the open and close of an outreach window you define with window_lead_days and window_lag_days, which default to 70 and 42. window_status is one of open, not_yet, closed_passed or no_event and is the field to filter on. Dates are PREDICTED from filing history, not announced: read next_event_is_estimate and confidence_band, whose thresholds sit at 0.80 and 0.50. TIMING ROWS COVER US COMPANIES ONLY. A non US company resolves fully for identity and returns a stated timing_unavailable_reason rather than a guessed date, and is still charged as a timing row because the work ran. Charged per timing row returned, never additionally as a resolved company. Requires an APIFY_TOKEN and consumes Apify credits. Read only.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
ciksNoSEC Central Index Keys, with or without leading zeros.
leisNo20 character Legal Entity Identifiers.
isinsNo12 character ISINs.
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.
tickersNoExchange tickers, e.g. NWLG. Matched against the primary ticker and every venue listing.
cadencesNoquarterly, semiannual, annual, unknown.
event_typesNofull_year_results, half_year_results, quarterly_results, trading_update, annual_report_publication, sustainability_report_publication, agm, proxy_filing, capital_markets_day.
company_namesNoLegal or trading names. Matched on a normalized name. Former names are not available: the alias table carries tickers and ISINs only.
country_codesNoISO 3166-1 alpha-2, e.g. US, GB, FR.
company_domainNoA single bare domain, e.g. stripe.com. The Clay column shape. Used by resolve, qualify and timing.
exchange_codesNoISO 10383 MICs. 18 venues are covered.
security_typesNoordinary_shares, depositary_receipt, preferred_shares.
company_domainsNoMany domains at once. Used by resolve, qualify and timing.
window_lag_daysNoHow many days before the event the outreach window closes. Default 42. Must be less than the lead.
window_statusesNoKeep only rows in these window states: open, not_yet, closed_passed, no_event.
window_lead_daysNoHow many days before the event the outreach window opens. Default 70.
max_days_to_eventNoDrop rows whose next event is further away than this. A cost control.
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.
min_cadence_confidenceNo0 to 1. Rows whose cadence confidence falls below this return a null timing block with a stated reason rather than a guess. Quarterly cadence averages 0.94, annual 0.40, semiannual 0.21.
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.
include_constrained_periodNoEmit the period in which a listed company is constrained in what it can announce, derived from the same window numbers. Useful for campaign and announcement timing.
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

A3.7/5.0
Behavior2/5

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

The description is unusually rich about behavior beyond the annotations: dates are PREDICTED not announced, estimate/confidence thresholds at 0.80 and 0.50, per-row credit charging, APIFY_TOKEN requirement, and the non-US no-guess policy. However, it closes with 'Read only.' while the annotations declare readOnlyHint=false, a direct conflict on the read/write axis that an agent may rely on when deciding whether a call has 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.

Conciseness4/5

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

One dense passage with no filler: purpose first, then the returned shape, then the prediction caveat, then the US-only and billing constraints last. It is long, but every sentence carries a fact an agent needs; the only cost is that the constraint/cost material is buried in a paragraph rather than surfaced separately.

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 30-parameter, no-required-parameter tool with no output schema, the description supplies the missing return-value semantics (field names, window_status vocabulary, estimate flags, confidence bands) and the commercial/geographic constraints an agent cannot infer from the schema. Nothing material for correct invocation 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 description coverage is 100%, so the baseline is 3, and the description earns above baseline by tying parameters to meaning the schema does not: window_lead_days/window_lag_days (70/42) define the window whose state window_status reports, min_cadence_confidence interacts with null timing blocks, and 'which is the field to filter on' tells the agent that window_statuses is the primary dial. It does not attempt to explain the other ~25 filter parameters, which the schema already covers.

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 gives a specific verb and resource: it predicts when a public company next reports and defines an outreach window around that event, with a concrete list of returned dimensions (next reporting event, days to event, window open/close). It is clearly a timing tool and not an identity or qualification tool, but it never names or contrasts itself with the sibling get_reporting_season, which is the tool an agent is most likely to confuse it with.

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 states a hard applicability boundary ('TIMING ROWS COVER US COMPANIES ONLY') and what happens outside it (a stated timing_unavailable_reason rather than a guess, still billed), plus which field to filter on (window_status) and that max_days_to_event is a cost control. What is missing is routing guidance against the sibling alternatives (get_reporting_season, resolve_company, qualify_company) for the same company set.

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

Deploy Server

Other Tools