filingpulse

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's contribution is the disclosure that results are sorted newest-first and returned in a {data, total, limit, offset} envelope. The paginated envelope shape is genuinely useful context an agent cannot infer from annotations, though permission/rate-limit behavior remains unstated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two tightly packed sentences: the first defines the resource and its ordering, the second covers filtering and the return envelope. Nothing is redundant and the highest-value information leads.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description fills that gap by naming the response envelope, and all seven parameters are documented in the schema. For a read-only filtered listing endpoint, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including the ticker-to-CIK resolution caveat. The description restates the filterable fields but adds no syntax, defaults, or constraints beyond what the schema provides, making 3 the correct baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('List SEC 8-K corporate events') with classification scope ('by official item code') and ordering ('newest first'), which cleanly separates it from siblings like get_insider_filing and get_ipo_registrations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Enumerates the available filter axes (item code, issuer ticker, CIK, since-date) and gives concrete item-code examples, so the agent knows how to scope a query. It never names a sibling as an alternative or states when a different tool would be preferable, so it stops short of explicit when-not guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false, destructiveHint=false), so the lower bar applies. The description adds genuine behavioral context by disclosing that the response reports data freshness and coverage boundaries, which tells the agent the corpus is not necessarily up to the current date.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two sentences, tightly written, with the return contents front-loaded and the usage cue second. Every clause earns its place and only one call-to-action is given.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and no output schema, the description must convey what the agent gets back, and it does so adequately (counts, ingest timestamps, earliest covered filing date). It stops short of stating the result shape or units, but it is complete enough for a zero-argument status tool.

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

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

The tool takes no parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. The listed return fields describe output, not inputs, and correctly do not pretend otherwise.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the specific resource (each dataset) and enumerates the exact fields returned — row counts, latest ingest timestamps, earliest covered filing date — plus concrete dataset types (Form 4, 8-K, registrations). It is clearly distinguishable from siblings like get_schema and the get_insider_* query tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Call this to learn what date range a query can be answered from" gives an explicit use context and frames it as a prerequisite check before querying. It does not name an alternative tool or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully adds what comes back (transaction legs, holdings, footnotes), but says nothing about failure modes for an unknown accession or pagination/size limits on large filings.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

One sentence, front-loaded with the verb and resource, with the identifier and the return payload following immediately. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description partially compensates by enumerating the returned contents (legs, holdings, footnotes), which is enough for an agent to know what it gets. A note on error behavior for an invalid accession would make it fully complete.

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

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

Schema description coverage is 100% and the single accession parameter is already fully documented including an example, so the schema carries the load. The description repeats the same example format without adding constraints such as whether the dashes are optional or whether a CIK-based lookup is accepted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ("Fetch") plus a precise resource ("one Form 4 insider-transaction filing") and the identifying key (SEC accession number). The word "one" signals a single-record lookup rather than a list, but the description never names or contrasts with the closely related sibling get_insider_trades, so differentiation is left implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer it should call this when it already holds an accession number. There is no explicit when-to-use versus when-not-to-use statement, and no mention of get_insider_trades as the alternative for browsing or filtering insider activity.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: newest-first ordering, numeric values returned as filed strings, an accession/filed_date on every object, and the fact that data is hosted and pre-normalized (no EDGAR crawling). Return format detail is slightly thin, but the extra traits are substantive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two dense sentences that front-load the resource and scope before the filters and return shape. It is information-rich and largely earns its length, though the content list and normalization note make it slightly heavier than strictly necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly carries the return-shape burden, naming the {data, total, limit, offset} paging envelope and per-object guarantee of accession and filed_date. Combined with the filter and normalization notes, an agent has everything needed to invoke and page through it.

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

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

Schema description coverage is 100%, so every parameter is already documented, making 3 the baseline. The description reinforces the filter set (ticker, CIK, form_type, since-date) and explains the {data, total, limit, offset} envelope, but omits the 'until' window and adds no syntax beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (List) and resource (normalized SEC Form 4 insider-transaction filings) with scope details (non-derivative and derivative legs, holdings, owner roles, footnotes, amendment links). This clearly differentiates it from the sibling get_insider_filing, which implies a single filing rather than a listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete filter axes (issuer ticker, CIK, form_type, since-date) that tell the agent when this tool is the right pick for filtered listing. It stops short of explicitly naming an alternative or a when-not condition, so the routing is strongly implied rather than stated.

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

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

Annotations cover the safety profile (read-only, non-destructive, closed-world), so the bar is lower, yet the description still adds real behavior: newest-first ordering, cross-stage threading via file number, the historical coverage boundary, and the exact {data, total, limit, offset} response envelope. It does not mention auth requirements or throttling, so not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Four front-loaded sentences, opening with verb+resource and ordering, then enrichment, then coverage caveat, then return shape. Every sentence carries information an agent would otherwise have to discover empirically; no boilerplate or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by describing the envelope and field-level content of issuer objects, and all 8 parameters are documented in the schema. Remaining gaps are minor: no mention of permission/auth requirements and no explicit contrast with the detail-oriented get_registration_event sibling.

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

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

Schema coverage is 88%, so the baseline is 3, but the description adds semantics the schema lacks: file_number is described as following one offering across lifecycle stages, the stage filter is mapped to concrete filing forms, and the issuer object's fields (SIC code, state of incorporation, former names) are surfaced. It does not explain since/until interplay beyond what the schema already notes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource with enumerated scope: 'List S-1/F-1 registration lifecycle events' covering registration statements, amendments, EFFECT notices, and 424B1/424B4 prospectuses. It is far more precise than a generic 'get filings'. However, it never distinguishes itself from the singular sibling get_registration_event or from get_corporate_events, so the sibling-differentiation element of a 5 is missing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operative context: results are ordered newest first, records are threaded by SEC file number, and coverage is 'live-forward since 2026-08-01', which tells the agent exactly which queries will return data. It stops short of naming an alternative tool or stating when-not to use it, so no explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds only the domain scope (S-1/IPO registration lifecycle) and that it returns a single event; it says nothing about behavior when the accession number is unknown or whether results are cached/stale.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

A single tight sentence with the key lookup mechanism front-loaded and zero filler. Nothing could be removed without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read-only lookup with full schema coverage and complete annotations, the description supplies what is needed to call it correctly. The one remaining gap is the relationship to get_ipo_registrations, which would help disambiguation.

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

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

Schema description coverage is 100% and the schema documents the sole accession parameter, so the baseline is 3. The description restates the lookup key ('by SEC accession number') without adding format, validation, or example detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (Fetch) and resource (S-1/IPO registration lifecycle event) and scopes it to a single record, so an agent knows it is a point lookup by accession number. It does not, however, distinguish itself from the sibling get_ipo_registrations, which an agent could easily 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus the closely named get_ipo_registrations sibling, nor any prerequisite or exclusion guidance. Usage is only inferable from the word 'one'.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the lower bar applies. The description adds genuine behavioral context beyond the annotations: the schema is 'frozen' and 'additive-only', and the design rules (strings-as-filed, null-never-missing) tell the agent what guarantees the data contracts hold.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

A single dense sentence that front-loads the resource ('the frozen schema-v1 contract for FilingPulse objects') then lists contents via a colon. No filler, no redundancy, appropriate length for a reference tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must convey what a caller gets back, and it does so by naming the sections and design rules. For a one-parameter, read-only reference tool this is nearly complete; only the 'overview' default value and a hint that this is static documentation are not spelled out.

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

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

Schema description coverage is 0%, so the description must compensate. It enumerates content areas matching five of the six enum values (form4, event_8k, registration_event, list envelope, transaction_codes), with 'design rules' implicitly covering the default 'overview' section. It could be sharper about the default, but the mapping is largely recoverable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (the frozen schema-v1 contract) and enumerates exactly what it documents: form4, event_8k, registration_event, the list envelope, design rules, and the transaction-code table. This clearly separates it from all sibling tools, which fetch data rather than describe the data contract.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated — an agent infers it should call this to learn the schema before interpreting other tools' output. There is no explicit when-to-use or when-not-to-use guidance, nor any statement that this is a prerequisite/companion to the sibling data tools.

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