OpenFilings

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.22.0
Disambiguation3/5
Most tools target distinct resources or actions, but filing_outline and filing_sections are nearly identical, both returning headings without section bodies. Additionally, filing_read, filing_markdown, and filing_search could be confused if descriptions are not carefully read, though their purposes are subtly different.
Naming Consistency3/5
Tool names mostly follow an object-first pattern (e.g., filings_list, companies_search), but the action placement is inconsistent—sometimes at the end (filings_diff, financials_query) and sometimes absent or noun-based (filing_outline, company_research_brief, company_facts). This mix makes the naming less predictable than a uniform verb_noun scheme.
Tool Count4/5
22 tools is on the higher end but appropriate for a comprehensive filings domain that spans company research, filing retrieval, structured financial queries, ownership data, and historical backfill. The count is not excessive given the breadth, though one redundant tool pair slightly inflates it.
Completeness4/5
The tool set covers the core workflows: locating companies, listing and reading filings, extracting structured financial facts, comparing filings, and monitoring new submissions. It also includes an import tool for external filings. Minor gaps exist (e.g., no full-text search for insider dealings), but the surface is largely complete for the intended use.
Average 3.1/5 across 22 of 22 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 69 commits in the last 12 weeks
- Last stable release on August 1, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the basic action (import to cache) but does not mention side effects, permissions, whether it overwrites existing entries, rate limits, or any error conditions. This is a significant gap for a tool that modifies local state.
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?
The description is a single focused sentence with no redundant words. It front-loads the core action and resource, making it easy to grasp. However, the brevity sacrifices necessary detail for a tool with 7 parameters, so it is concise but not optimally structured for completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter import tool with no annotations and minimal description, this is severely incomplete. It does not explain return values, behavior on repeated imports, or how parameters interrelate. Although an output schema exists, the description alone leaves critical gaps that prevent an agent from using it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 7 parameters. It only hints at document_url via 'PDF URL', leaving required fields like company_id, title, filing_date, and optional fields like category, period_end, filing_type completely unaddressed. This fails to guide the agent in constructing valid calls.
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?
Description clearly states the action (import) and resource (one official SEDAR+ generated PDF URL into local cache). This distinguishes it from siblings like filing_read or filings_list. However, it doesn't elaborate on what 'import' entails (download, parse, store), which keeps it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or scenarios where this tool is preferred over filing_read or filings_list. The implied usage (import a PDF URL into cache) is present but there is no explicit context or direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It mentions 'locally stored' and 'restatement-aware semantics' which hints at data locality and restatement handling, but it does not explain what restatement-aware means, whether results reflect as-reported or restated values, or any side effects. The description is vague and fails to disclose important details about output behavior or constraints.
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?
The description is a single, front-loaded sentence that concisely states the core action. It avoids unnecessary words and is easy to parse. It is appropriately brief for a simple query tool, though the brevity comes at the cost of essential details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has five parameters, an enum, and restatement-aware semantics, the description is far too sparse to be complete. It does not explain the view modes, the as_of date behavior, or the meaning of codes and limit. Although an output schema exists, the description still needs to explain how to use the tool, which it does not. The agent would struggle to use this correctly without external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no explanation of the five parameters (view, as_of, codes, limit, company_id). The enum for 'view' and the date logic for 'as_of' are left completely unexplained. The description's phrase 'restatement-aware semantics' does not translate to parameter meaning, leaving the agent to guess how to set parameters correctly.
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 clearly states the tool queries locally stored filing facts, with the specific qualifier 'restatement-aware semantics' indicating a key differentiator from sibling tools like company_facts or financials_query. The verb 'query' plus the resource 'filing facts' makes the core purpose unambiguous, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or conditions for selecting this over sibling tools. The description merely states what it does, leaving the agent to infer usage context from the name and parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. The description only says 'Return', which implies a read operation, but it doesn't explain behavior around parameters like refresh (which might trigger side effects), detail levels, or edge cases. It lacks any commentary on safety, caching, or mutation.
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?
The description is a single concise sentence with no filler. It front-loads the core action. However, it may be too terse for the tool's complexity, but it is appropriately concise for a summary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the six parameters, lack of annotations, and specific sibling tools, the description is under-specified. It doesn't mention the required filing_id, provide context on return values (though output schema exists), or explain how it differs from similar tools like financials_query. The tool is moderately complex, and the description leaves major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage for its 6 parameters. The description provides partial mapping: 'selected statements' likely refers to the statements parameter, 'bounded periods' to periods, and 'line items' to max_line_items. However, it does not explain filing_id, detail, or refresh. Since schema coverage is 0%, the description inadequately compensates.
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 clearly states the tool returns selected statements with bounded periods and line items, indicating the resource (financial statements) and action (return). It is not a tautology. However, it doesn't explicitly mention it's from a filing, though the tool name and required filing_id imply this, and it doesn't differentiate from siblings like financials_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, exclusions, or alternative tools. Given the array of sibling tools, this is a clear gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'List structured...' which implies a read operation, but does not disclose behaviors such as pagination, authorization requirements, or error handling.
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?
The description is a single, clear sentence with no redundant words. It is highly efficient and front-loaded, earning every word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the presence of an output schema, the description lacks essential context such as what constitutes a 'UK or Brazilian issuer', how the list is sorted or paginated, and when to use this tool. Given no annotations and poor parameter coverage, it is insufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the meaning or purpose of the 'company_id' or 'limit' parameters. It only vaguely implies that an issuer is needed, but adds no value beyond the schema.
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 clearly states the tool's function: listing structured major-holder records for a UK or Brazilian issuer. It uses a specific verb and resource, but does not explicitly distinguish from the sibling tool 'major_holders_search'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like 'major_holders_search' or other siblings. The description only states what it does without indicating appropriate usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The term 'statelessly' discloses that the call does not depend on prior state, which is useful behavioral context. However, with no annotations provided, the description does not go further to explain effects (e.g., whether a watchlist must exist), potential side effects, or data scope, leaving the burden largely unaddressed.
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?
The description is a single sentence and is not padded with unnecessary details. It is front-loaded with the core action ('return filings') and quickly specifies the key filter. However, the brevity comes at the cost of missing context, so it is concise but not fully effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters and an output schema, the description is too terse to be fully useful. It omits the relationship between company_ids and the returned filings, what 'watchlist' implies, and the meaning of `source`, leaving an agent with incomplete information for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 clarifies the `since` parameter's role as a date cutoff, but it does not explain `company_ids` beyond the schema's property name, nor does it elaborate on the `source` parameter and its default 'all' value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'return[s] filings published on or after since', identifying a clear verb and resource with a date filter. However, it does not clarify the role of company_ids or what 'watchlist' refers to, and it does not differentiate this tool from siblings like filings_list or filing_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as filings_list or filing_search. The description neither provides context for typical use cases nor mentions exclusions, so an agent receives no help in selecting among the many filing-related sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is responsible for disclosing behavioral traits. It only mentions data sources and gives no details about search behavior (e.g., exact vs fuzzy matching), processing of limit/scan_limit, ordering, or rate limits. The scope information is useful but insufficient.
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?
The description is a single sentence of 12 words, with no fluff or repetition. It is appropriately concise for the minimal information it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description lacks essential context such as parameter behavior and usage constraints. With no annotations and low schema coverage, it leaves the agent under-informed about how to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It does not mention holder_name search semantics or the meaning of limit and scan_limit. The parameter names are self-explanatory at a basic level, but the description adds no additional value beyond their existence.
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 clearly states the action ('search') and the domain ('holder positions across UK notifications and Brazilian FRE data'), making the tool's purpose distinctive from siblings like major_holders_list. However, it does not explicitly contrast with those siblings or clarify what constitutes a 'holder position'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as major_holders_list or disclosures_search. The description offers no context about scenarios where this search is appropriate or how it differs from related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits, but it only adds 'using compact metadata', which is vague and may describe either the input or output. It does not mention matching behavior, response format, authentication, rate limits, or any side effects. This is a significant gap for a tool that the agent is encouraged to use as a workflow entry point.
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?
The description is a single concise sentence with two clauses, front-loading the primary action ('Find companies') and adding a strategic usage hint. There is no redundancy or wasted words. It is appropriately sized for a straightforward search tool, though it could have been slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The existence of an output schema reduces the need to describe return values, but the description omits critical usage context such as how the query is matched, what values are valid for 'source', and what 'compact metadata' means. Given the tool's role as a workflow starting point, the description leaves too many operational questions unanswered for an agent to invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the three parameters (query, limit, source). While 'query' and 'limit' are somewhat intuitive, 'source' with a default of 'all' is ambiguous and could refer to data source, publication source, or something else. The description adds no meaning beyond the parameter names, failing to compensate for the schema's lack of descriptions.
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 clearly states the tool's function: 'Find companies using compact metadata'. It goes beyond a tautology by indicating the resource (companies) and hints at the output nature (compact metadata). It differentiates from sibling search tools (disclosures_search, filing_search, major_holders_search) by targeting companies specifically, and the phrase 'start most company workflows here' signals a primary entry point.
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?
The description provides clear use context: 'start most company workflows here' tells the agent this is the recommended initial step for company-related tasks. It implies that for detailed company data, one would use more specialized tools (e.g., company_facts, financials_query), but does not explicitly name alternatives or exclusion criteria. This gives solid guidance without being exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It does reveal that responses are 'bounded, paginated', which is a positive trait, but it fails to explain what 'bounded' means (e.g., via max_chars), how pagination works (offset), whether refresh has side effects, or whether any permissions are needed. The safety profile (read-only) is only implied by the word 'Read', which is insufficient.
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?
The description is a single, front-loaded sentence with no filler or redundant information. It conveys the core purpose and a key behavioral trait (bounded, paginated) in just ten words, earning high marks for conciseness and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (which covers return values), the description is incomplete for a tool with five parameters. It lacks any guidance on required fields (filing_id, section), optional parameters (offset, refresh, max_chars), or prerequisites like obtaining the section name. The brevity leaves the agent to guess parameter usage, making the description insufficient for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
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, but it does not explain any of the five parameters. The phrase 'bounded, paginated' loosely relates to max_chars and offset, but no parameter names or meanings are given. For a tool with multiple parameters, this is extremely inadequate; the agent cannot correctly map arguments from the description alone.
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?
The description clearly states the tool reads one named filing section, using the verb 'Read' with a specific resource ('one named filing section') and notes the bounded, paginated response. This distinguishes it from siblings like filing_sections (lists sections) and filing_markdown (full text), making it distinct among the filing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when a specific named filing section is needed), and the phrase 'one named filing section' hints that the section name must already be known, possibly from filing_sections. However, it provides no explicit guidance on when not to use it or alternatives, leaving usage context mostly inferential.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the transparency burden. It discloses that results are ranked and bounded, which is meaningful behavioral context, but it does not explain ranking criteria, match behavior, or response structure. This provides basic transparency but lacks depth.
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?
The description is a single 9-word sentence that is front-loaded and contains zero filler. Every word earns its place, and it avoids repeating schema titles.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value details need not be in the description. However, for a tool with four parameters, no annotations, and a sibling set containing similar filing tools, the description lacks usage context and parameter detail, making it minimally adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only loosely implies parameter roles: 'one filing' suggests filing_id, 'search' suggests query, and 'bounded excerpts' hints at limit and snippet_chars. It does not name parameters or clarify semantics like default behavior or how bounds are applied, so it insufficiently compensates for the missing schema descriptions.
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 uses a specific verb ('Search') and resource ('one filing') and clarifies the result is 'ranked, bounded excerpts.' This distinguishes it from broader search or read siblings, though it does not explicitly name alternatives, so it falls short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use filing_search versus siblings like filing_read, filing_sections, or disclosures_search. The description only states what it does; no exclusions, prerequisites, or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It usefully discloses that the tool returns only headings (not section bodies), which is a key behavioral trait. However, it omits other potentially relevant details such as authorization requirements, rate limits, or handling of invalid filing IDs.
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?
The description is a single, well-structured sentence that conveys the essential function without redundant language. It is front-loaded with the tool's role and core outcome.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The presence of an output schema reduces the need to describe return values. However, the description lacks usage guidance and parameter semantics, which are critical for an agent to confidently select this tool over similar filing tools. It is minimally complete but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description should compensate by explaining parameter meanings and relationships. It does not mention any of the three parameters (filing_id, limit, query). The schema provides names and types but no descriptions, leaving the agent to infer semantics from names alone.
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 clearly states the tool returns headings without section bodies, specifying the verb 'returns' and the resource (headings). However, it does not explicitly differentiate from the sibling tool 'filing_outline', which likely serves a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives like filing_outline, filing_read, or filing_markdown. There is no mention of use cases, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states that it lists compact metadata, but does not disclose filtering options, default limits, history_days behavior, or output characteristics. Given the tool has five parameters, this is a significant gap.
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?
The description is a single concise sentence with no redundant words, effectively communicating the core function in seven words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has five parameters and many related siblings, but the description provides minimal context. It lacks guidance on parameter usage, relationships to other filing tools, and any nuances beyond the basic metadata-only scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not mention any parameter, leaving limit, source, category, company_id, and history_days unexplained. The description adds no value for understanding these parameters.
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?
The description specifies the action 'List' and the resource 'compact filing metadata', and explicitly excludes downloading document content, which distinguishes it from content-focused tools like filing_read and filing_markdown.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when metadata is needed, but does not explicitly state when to use it over alternative tools or when not to use it. The 'without downloading document content' provides some context but lacks direct comparison to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that results are filtered ('only selected'), span multiple periods ('multi-period'), and include provenance, which adds useful context. However, it does not explain the nature of provenance, any limitations, or whether the query is read-only, leaving gaps in behavioral disclosure.
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?
The description is a single, tightly worded sentence that front-loads the key information with no redundancy. Every phrase ('only selected', 'multi-period', 'with provenance') contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return-value details are not required. However, given the tool's moderate complexity (4 parameters, 2 required) and several closely related sibling tools, the description lacks usage guidance and parameter semantics needed to fully disambiguate. It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 loosely maps 'selected' to the 'codes' parameter and 'multi-period' to 'periods', but it does not explain the meaning of 'source', 'company_id', or how the parameters interact. The description adds minimal value over the raw schema.
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 uses a specific verb ('Return') and resource ('financial facts') with qualifiers ('selected multi-period', 'with provenance'), making the core function clear. It distinguishes itself from siblings like historical_facts_query or company_facts by emphasizing selectivity and provenance, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus siblings such as company_facts or filing_financials. The description only implies a narrowed scope ('only selected') but does not state exclusions, prerequisites, or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the download action but does not disclose side effects such as whether data is overwritten, whether authentication or rate limits apply, or what 'local storage' entails. This is insufficient for a tool that writes data.
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?
The description is a single concise sentence with a clear verb and object, front-loaded and free of jargon or unnecessary words. It earns its place despite being terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity with three parameters and no annotations, and the description is too minimal to support correct invocation. It lacks usage criteria, parameter details, and behavioral implications, making it incomplete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero descriptions for its three parameters, and the description does not compensate. It only hints that 'UK/ESEF' relates to the source enum, but does not explain company_id or limit. The meaning must be inferred from parameter names.
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?
The description clearly states the tool downloads UK/ESEF structured filing history into local storage, naming a specific verb (download), resource (filing history), and scope (UK/ESEF). This differentiates it from sibling tools like filings_list or filing_read that focus on viewing or querying, not bulk downloading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention any exclusions, prerequisites, or comparisons to sibling tools such as filings_list or historical_facts_query, leaving the agent without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It adds 'parsed into structured fields,' which hints at output formatting, but does not disclose behaviors such as sorting, pagination, or any limitations. It does not contradict annotations (none exist), but it provides minimal additional context beyond the tool's name.
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?
The description is a single, focused sentence that conveys the core function without fluff. It is well-structured and efficient, earning a high score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (two parameters, output schema exists), but the description is too sparse to be complete. It does not explain what structured fields are returned, nor any edge cases or usage context. The existence of an output schema helps, but the description itself leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not elaborate on parameters. However, the parameter names are self-explanatory (company_id and limit), and limit has a default. The description adds no semantic value beyond the schema, so a score of 2 is appropriate.
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?
The description clearly states 'List UK MAR director/PDMR/PCA dealings parsed into structured fields.' It specifies the verb (List), the resource (dealings), and the scope (UK MAR director/PDMR/PCA), which distinguishes it from sibling tools like major_holders_list or disclosures_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention when not to use it, nor does it reference sibling tools. The usage context is implied by the tool name and description, but there is no explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It implies a read-only 'report' operation but does not explicitly state safety, potential side effects, or the nature of validation performed. Additional context such as whether it requires special permissions or returns sensitive data is missing.
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?
The description is a single, front-loaded sentence that directly states the tool's function without any filler or redundancy. It earns full marks for conciseness and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the core purpose and an output schema exists (freeing the description from explaining return values), it lacks usage guidance and behavioral transparency. For a tool with one parameter and no annotations, more context is needed to fully support agent decision-making, making this incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter (filing_id) with 0% description coverage. The description's phrase 'for one filing' implicitly connects to this parameter but provides no additional meaning about the format or expected values. Since the parameter is self-explanatory, this minimal compensation is acceptable, though it does not fully offset the lack of schema documentation.
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?
The description 'Report extraction provenance, confidence, and validation for one filing' clearly identifies the tool's purpose with a specific verb and resource. It distinguishes itself from sibling tools like filings_list or filing_read by focusing on data quality metadata rather than listing or reading filing content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention use cases, prerequisites, or scenarios where this tool is preferred over other filing-related tools, so agents lack context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a read-only comparison but does not explicitly state that no changes are made to filings, nor does it disclose any permissions, side effects, or edge cases (e.g., what happens when there are no changed values). The phrase 'return changed values' hints at output but lacks detail.
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?
The description is a single, well-structured sentence that efficiently conveys the core purpose. It is appropriately sized, has no redundant content, and is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is conceptually simple with a clear output schema available, so a brief description may suffice. However, it lacks context on how the IDs are used, what 'normalized facts' means, and whether the tool requires any preconditions (e.g., filings must exist and be comparable). The description is minimal but not entirely inadequate for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameter descriptions (0% coverage), and the description only says 'two filings' without explaining the purpose or format of first_filing_id and second_filing_id. It does not clarify the type of IDs expected (e.g., filing IDs vs. accession numbers) or the relationship between the two parameters. The description adds minimal value beyond the schema.
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?
The description clearly states the tool's function: 'Compare normalized facts in two filings and return changed values.' It uses a specific verb (compare) and resource (filings), and the context (normalized facts, changed values) distinguishes it from siblings like companies_compare or filing_read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or scenarios where other tools (e.g., filing_read or companies_compare) would be more appropriate. The description simply states what it does, leaving usage decisions to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It only states the action 'compare' without explicitly confirming that it is a read-only operation, nor does it explain the 'normalized fact' processing or any limitations. The agent cannot infer safety or side effects from this minimal description.
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?
The entire description is one sentence with no filler or redundant phrasing. It is front-loaded with the action word 'Compare' and immediately gives the scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters, no annotations, and a critical need for parameter clarification, this one-sentence description is incomplete. It doesn't explain what 'normalized fact' means, how to specify sources, or what the output represents, leaving significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 gives context for `code` as the 'normalized fact' and for `company_ids` as the range of two to twenty issuers, but it fails to explain the `source` parameter or the format of the identifiers. This is insufficient for a tool with three parameters.
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?
The description uses the specific verb 'compare' and specifies the resource: 'one normalized fact across two to twenty UK/ESEF issuers.' This clearly distinguishes the tool from sibling tools like company_facts or financials_query, which likely focus on single-company data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for cross-company comparison but does not explicitly state when to use it instead of alternatives like financials_query or disclosures_search. No exclusions or alternative references are provided, so the guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden. It does add scope ('only' headings and sizes) and the selection use case, but it does not disclose behavior around the `refresh` flag, caching, failure modes, or the meaning of 'sizes'. This is a minimal but non-contradictory addition.
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?
One concise sentence, front-loaded with the core action, and no wasted words. It is appropriately short for the simplicity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks context about when this is preferable to sibling tools, what `limit` and `refresh` do, and any caveats. Though an output schema exists, the absence of usage guidance and parameter explanation makes it incomplete for effective tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
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 does not explain `filing_id` (though obvious), `limit`, or `refresh`. The phrase 'headings and sizes' relates to output, not input parameters. No parameter semantics are provided beyond the schema's names and defaults.
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?
The description uses a specific verb ('Return') and identifies the resource ('headings and sizes') with a clear scope constraint ('only'). It distinguishes the tool from siblings like filing_read or filing_markdown by signaling that this is a structural outline, not full content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'allowing targeted section selection' implies the use case, but it does not explicitly name alternatives or state when not to use this tool. No exclusionary guidance is given relative to sibling tools like filing_sections or filing_read.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the read-only nature ('Read') and bounded output ('bounded'), but does not explain offset/refresh/ocr_mode behavior, pagination, or error cases. It adds some useful context but leaves significant behavioral traits unstated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded with no filler, which is positive. However, it is under-specified for a five-parameter tool—essential parameter semantics are missing, so conciseness comes at the cost of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given five parameters, no annotations, and zero schema description coverage, the description is too sparse. It does not explain offset, refresh, ocr_mode, or max_chars semantics, and only provides sibling guidance. The output schema may cover return values, but input behavior remains largely unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not name any of the five parameters. 'Bounded' hints at max_chars and 'Read' implies filing_id, but the semantics of offset, refresh, and ocr_mode are entirely unaddressed, so the description fails to compensate for the schema's lack of parameter descriptions.
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?
The description clearly states a specific verb ('Read') and resource ('bounded Markdown page'), and further distinguishes itself from siblings by saying to prefer outline, search, or section tools. This makes the tool's purpose unmistakable and differentiates it from filing_read, filing_outline, etc.
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?
The phrase 'prefer outline, search, or section tools' gives explicit guidance to use alternatives when possible, implying this tool is a fallback for whole-page Markdown reads. It does not specify exact conditions (e.g., 'use when you need full text'), but it provides clear contextual direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It does disclose the core behavior of merging filings into a multi-period fact series, but it does not explain how 'most recent' filings are selected, how line items are normalized, or any potential limitations. This is moderate transparency given the absence of annotations.
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?
The description is a single, well-structured sentence with no fluff. It front-loads the core action and includes a useful contrast clause. Every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, an output schema, and is one of many related tools, the description provides only the essential purpose. It lacks guidance on parameter selection, data coverage, and edge cases. While the output schema may handle return values, the description alone is insufficient for an agent to fully understand how to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not elaborate on any parameters. It only hints at 'multi-period' and 'line item' which might relate to 'periods' and 'max_line_items', but it does not explain the meaning of 'detail', 'source', 'statements', or the exact behavior of the parameters. The description adds minimal value beyond the schema fields themselves.
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?
The description clearly uses a specific verb ('Merge') and identifies the resource ('a company's most recent structured filings') and the output ('one multi-period fact series per line item'). It distinguishes from sibling tools like filings_list and financials_query by emphasizing consolidated multi-period data rather than individual filings.
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?
The phrase 'instead of one filing at a time' provides implicit usage guidance, suggesting this tool is for aggregating across filings when a per-filing view is insufficient. However, it does not explicitly name alternative tools or state when not to use it, so it falls slightly short of full clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does this well by explaining that ownership and director-dealing data are omitted due to source coverage differences and cautioning that missing data should not imply no activity. This is valuable behavioral context beyond the basic purpose, though it doesn't cover aspects like error handling or output structure, which are partially addressed by the output schema.
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?
The description is extremely concise, with two short sentences/paragraphs. The first sentence states the core purpose, and the second provides a crucial caveat. There is no filler or repetition; every word earns its place, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's primary function and a key caveat, but it lacks essential parameter semantics (especially 'source') and doesn't explicitly relate the tool to siblings like filings_list or financials_query. Given the presence of an output schema, return structure is covered, but the absence of parameter guidance is a significant gap for a tool with only two parameters and no schema descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain either parameter. The purpose mentions 'recent filings' and 'financial profile' but doesn't clarify what 'source' means (e.g., valid sources, format) or the exact role of 'company_id' beyond its name. This leaves the agent with insufficient information to correctly set the 'source' parameter, which has a default but no enumerated options.
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?
The description explicitly states the tool's function: 'Return recent filings and a compact three-period financial profile.' This clearly identifies the verb (return), the resource (filings and financial profile), and distinguishes it from siblings like filings_list and financials_query. The mention of ownership and director-dealing data being in dedicated tools further differentiates its scope.
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?
The description provides context that ownership and director-dealing data are intentionally excluded and handled by dedicated tools, which implicitly advises when not to use this tool. It also warns that missing data must not be interpreted as no activity, offering guidance on interpreting results. However, it doesn't explicitly name the alternative tools or state 'use this tool when you need a quick brief.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It mentions the global scope, which is useful, but does not mention safety (e.g., read-only nature), rate limits, pagination, or response behavior. The reference to fca_nsm and cvm is more about tool availability than the tool's own runtime behavior.
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?
The description is two concise sentences with no redundant wording. The first sentence states the core functionality, and the second adds valuable cross-references to alternatives, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description conveys the core purpose and scope effectively, but it lacks depth in parameter semantics and usage exclusions. Given that there is an output schema, return values are covered, but the source parameter's meaning is only implied, and the tool's behavior under different source values is not explained. Overall, it is minimally adequate but not fully complete for a search tool with multiple sources.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain `keyword`, `limit`, or `source` explicitly. The only indirect hint is that fca_nsm and cvm are mentioned, which may correspond to the `source` parameter, but this is left implicit. This is inadequate for a tool with three parameters.
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?
The description clearly states the action ('Full-text search') and the specific resource ('every issuer's disclosures, not scoped to one company'). This distinguishes it from company-specific search tools like company_facts or company_research_brief. Mentioning fca_nsm and cvm as similar global search tools further clarifies its unique position among siblings.
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?
The phrase 'not scoped to one company' clearly implies use for cross-company searches, providing context. It also names alternative tools (fca_nsm, cvm) that support similar global search. However, it does not explicitly state when not to use this tool or name company-specific alternatives, so it lacks a full exclusionary guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![openfilings MCP server](https://glama.ai/mcp/servers/ryanrodrigues25200525-svg/openfilings/badges/card.svg)](https://glama.ai/mcp/servers/ryanrodrigues25200525-svg/openfilings)

Score Badge

Copy to your README.md:

[![openfilings MCP server](https://glama.ai/mcp/servers/ryanrodrigues25200525-svg/openfilings/badges/score.svg)](https://glama.ai/mcp/servers/ryanrodrigues25200525-svg/openfilings)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ryanrodrigues25200525-svg/openfilings'

If you have feedback or need assistance with the MCP directory API, please join our Discord server