Skip to main content
Glama
mambalabsdev

Public Company Reporting Window Finder

by mambalabsdev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Get Reporting Season

get_reporting_season
Idempotent

Map reporting load by week or month across a filtered public-company market to find busy and quiet weeks for campaign timing.

Instructions

Show how reporting load is distributed over time, so you can find the busy weeks and the quiet ones. Returns aggregate rows per bucket, not per company: period start and end, event count, company count, estimated share and mean confidence. Bucket by week or month with season_group_by, and optionally split by sector, country or exchange with season_split_by. The window defaults to today through 180 days out; set season_from and season_to for another. At least one filter is required and company identifiers are not accepted. Use this to plan campaign timing across a market, not to time one account; for a single company use get_reporting_timing. Narrow the population with the same filters build_company_universe takes (exchange_codes, country_codes, regions, sectors, public_float_bands, cadences). Charged per aggregate row returned, which is far fewer rows than the companies behind them. Requires an APIFY_TOKEN and consumes Apify credits. Read only.

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.
season_toNoseason mode. ISO date. Defaults to 180 days from today.
event_typesNofull_year_results, half_year_results, quarterly_results, trading_update, annual_report_publication, sustainability_report_publication, agm, proxy_filing, capital_markets_day.
season_fromNoseason mode. ISO date. Defaults to today.
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.
season_group_byNoseason mode. Bucket size.
season_split_byNoseason mode. Optional second dimension.
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.1/5.0
Behavior1/5

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

The description closes with 'Read only.' while the annotations declare readOnlyHint=false, a direct contradiction of the declared safety profile (flagged as Annotation Contradiction). Setting that aside, the description is otherwise rich — it discloses cost ('Charged per aggregate row returned'), auth ('Requires an APIFY_TOKEN and consumes Apify credits'), and the minimum-filter constraint — but the explicit contradiction with structured metadata forces the floor score.

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?

Front-loaded with the purpose and the return shape before any parameter talk, then progressively adds window defaults, constraints, routing, cost and auth. Nine sentences with essentially no filler; each carries either a routing rule, a constraint, or a cost/auth disclosure.

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?

With no output schema, the description carries the return-value burden and does so — aggregate rows per bucket with period start/end, event count, company count, estimated share and mean confidence. Combined with cost model, auth requirement, minimum-filter rule and sibling routing, an agent has everything needed to call this correctly for a 22-parameter 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?

Schema coverage is 100%, so the baseline is 3, but the description goes beyond it: it names the season-specific controls (season_group_by for week/month bucketing, season_split_by for a second dimension, season_from/season_to for the window), groups the population filters by family, and adds a constraint not encoded anywhere in the schema ('company identifiers are not accepted'). It stops short of explaining the semantics of individual filter enums, which the schema already covers.

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 ('Show how reporting load is distributed over time') and immediately names the sibling it is not for ('not to time one account; for a single company use get_reporting_timing'). An agent can distinguish it from get_reporting_timing and build_company_universe without opening any 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 routing rule ('Use this to plan campaign timing across a market... for a single company use get_reporting_timing'), an explicit hard precondition ('At least one filter is required and company identifiers are not accepted'), and a pointer to the filter vocabulary build_company_universe uses. When-to-use, when-not-to-use, and the alternative are all present.

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