SEC EDGAR financials, benchmarks, screening & Buffett value scans for agents. Pay x402 or API key.
Scored across 17 tools
Most tools have a clearly distinct scope: raw facts vs. financial statements vs. filing index, company-level vs. market-wide, and each scoring tool has a stated methodology. The only mild ambiguity is the cluster of ranking/score tools (buffett_scan, top_signals, standard_score, company_signal), but their descriptions draw explicit boundaries.
All names are lowercase snake_case and generally follow the same readable, descriptive style rather than mixing camelCase or vague verbs. Some are imperative verbs (lookup_company, screen_companies) while most are noun phrases, so it is not a uniform verb_noun pattern, but it is mostly consistent.
At 17 tools, the API sits just above the ideal 3-15 range and in the borderline heavy zone. Each tool has a distinct job, so it is not excessive, but the set is broader and heavier than a lean, well-scoped API.
The surface covers the core read-only workflow for SEC fundamentals: lookup_company, filings, raw facts, clean financials, peer benchmarks, industry aggregates, insider/ownership/short sentiment, and multiple screening/score families. There are no obvious dead ends for common agent workflows.
Rank US public companies by Quality Score (0-100) over a 10-year window from five components: return on invested capital (30 points, blended 60/40 with the company's industry percentile), durability through the cycle (20), cash conversion (20), balance-sheet strength (15) and capital discipline (15). Every component is explainable from the returned row (roic_median, fcf_conversion, net_debt_to_ebit, ...); a component with no usable data is dropped and the rest renormalized. Companies that stopped filing (4,313), have fewer than five fiscal years on file (1,702), lack the tags to measure returns on capital in enough of those years -- missing EBIT tags, or an unclassified balance sheet, common among homebuilders and industrials with captive finance arms (1,612) -- or are balance-sheet financials (banks, insurers, REITs; 1,539) are not scored and do not appear: 2,885 of 12,051 companies (roughly a quarter of all filers, ~37% of active ones) are scored today. Use it for price-independent quality; use buffett_value to add valuation. Methodology v3; heuristic screen, not investment advice. Cost: $0.25 per call; unpaid calls return a payment-required error.
| Name | Required | Description | Default |
|---|---|---|---|
| fy | No | Fiscal year of the published Quality Scores; omit for the latest. A year that isn't published returns an error listing the published years. | |
| limit | No | Maximum companies to return, 1-200. | |
| industry | No | 2-digit SIC industry group, e.g. 73 (business services, including software); omit for every industry. | |
| min_score | No | Minimum Quality Score, 0-100. | |
| min_revenue | No | Minimum annual revenue in USD, e.g. 1e9. | |
| exclude_foreign | No | Exclude foreign private issuers (20-F filers); set false to include them. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly and idempotent annotations, the description discloses the scoring methodology, exclusions of certain company types, the renormalization of components, the cost per call, and the payment-required error. It also notes the heuristic nature and methodology version, adding substantial behavioral context without contradicting the annotations.
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?
The description is long but information-dense, front-loading the core purpose and methodology before covering exclusions and usage. Every sentence adds value, though some details could be trimmed without losing meaning, keeping it slightly above average but not top-tier conciseness.
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?
Given the tool's complexity (6 parameters, no required, high schema coverage, and an output schema), the description covers purpose, methodology, exclusions, usage guidance, cost, and output explainability. With the output schema present, it doesn't need to detail return values, making it complete for an agent to use 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?
All six parameters are documented in the schema with clear descriptions (e.g., fy, limit, industry, min_score, min_revenue, exclude_foreign). The tool description adds little parameter-specific detail beyond what the schema already provides, so the baseline of 3 is appropriate.
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 clearly states the tool ranks US public companies by a Quality Score with a specific 10-year window and five weighted components. It explicitly distinguishes itself from the sibling buffett_value by noting the difference between price-independent quality and valuation, leaving no ambiguity about its purpose.
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?
It gives explicit guidance on when to use this tool ('Use it for price-independent quality') and directs to an alternative for valuation ('use buffett_value to add valuation'). It also mentions exclusions (companies not scored) and cost implications, providing comprehensive context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find high-quality US public companies trading below intrinsic value: the Quality Score (see buffett_scan) combined with a value score from the previous close (FCF yield, 10-year owner-earnings DCF margin of safety, P/E), ranked by combined_score, the mean of the two (0-100 each). Rows also carry market cap, owner-earnings yield and intrinsic value. Use buffett_scan for quality alone; it needs no price data. Foreign private issuers (20-F filers, e.g. Chinese ADRs) are excluded by default: they screen cheap for structural reasons fundamentals cannot see. Methodology v3; heuristic screen, not investment advice. Cost: $0.25 per call; unpaid calls return a payment-required error.
| Name | Required | Description | Default |
|---|---|---|---|
| fy | No | Fiscal year of the published Quality Scores; omit for the latest. A year that isn't published returns an error listing the published years. | |
| limit | No | Maximum companies to return, 1-200. | |
| industry | No | 2-digit SIC industry group, e.g. 73 (business services, including software); omit for every industry. | |
| min_score | No | Minimum combined_score (the mean of the quality and value scores), 0-100. | |
| min_revenue | No | Minimum annual revenue in USD, e.g. 1e9. | |
| exclude_foreign | No | Exclude foreign private issuers (20-F filers); set false to include them. | |
| min_margin_of_safety | No | Minimum DCF margin of safety (1 - market cap / intrinsic value), e.g. 0.2 for a price 20% below intrinsic value; 0 keeps companies at or below intrinsic value. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations: paid per call, payment-required error behavior, default exclusion of 20-F filers, methodology version, and a disclaimer that it is a heuristic screen, not investment advice. This goes well beyond the readOnly and idempotent hints already provided.
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?
The description is dense but every sentence earns its place: purpose, scoring detail, output fields, alternative tool, exclusions, methodology caveat, and cost. The most important information is front-loaded, and it remains concise given the tool's complexity.
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 tool with seven optional parameters and an output schema, the description is remarkably complete. It covers purpose, ranking, output contents, when to use an alternative, default filtering behavior, methodology, cost, and error conditions. There is no meaningful gap that would leave an agent unsure how to invoke 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 coverage is 100%, so parameters are already well documented. The description adds useful conceptual context by explaining that combined_score is the mean of quality and value scores supplies and identifying value score components (FCF yield, DCF margin of safety, P/E), which improves understanding of parameters like min_score and min_margin_of_safety.
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 ('Find'), a clear resource ('high-quality US public companies trading below intrinsic value'), and explains the scoring mechanism. It also differentiates itself from buffett_scan by explicitly combining quality and value scores, so an agent can distinguish the two 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?
The description explicitly tells the agent when to use the sibling buffett_scan instead ('quality alone; it needs no price data') and clarifies the default exclusion of foreign private issuers. It also mentions the cost and payment-required error, giving practical usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Raw normalized XBRL facts for one company as reported in its SEC filings, newest first: concept, value, unit, period_start and period_end, fiscal_year, fiscal_period, form, filed date and data-quality flags. Use it for individual reported values, quarterly figures or filing provenance; use company_financials for clean annual statements and ratios. Cost: $0.01 per call; unpaid calls return a payment-required error.
| Name | Required | Description | Default |
|---|---|---|---|
| cik | Yes | SEC Central Index Key (CIK), e.g. 320193 for Apple. Only have a ticker or company name? Call lookup_company first (free). | |
| limit | No | Maximum facts to return, newest first; up to 20000. | |
| concept | No | Canonical concept to return, e.g. revenue, net_income, total_assets, operating_cash_flow; omit for every concept. | |
| fy_from | No | Earliest fiscal year to include, by each filing's own fiscal-year tag (fiscal_year in the rows); omit for every year. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful context beyond those annotations: results are ordered newest first, rows include data-quality flags, and unpaid calls return a payment-required error. This gives the agent useful operational expectations without contradicting the annotations.
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?
The description is three sentences and every sentence earns its place: first defines the payload and ordering, second gives usage direction and the key alternative, third notes cost and failure behavior. It is front-loaded with the most important identifying information and contains no filler.
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?
Given the rich input schema, safety annotations, and stated output schema, the description covers all necessary operational context: what data is returned, how it is ordered, when to use it versus company_financials, and the payment-required error condition. There is no critical gap an agent would need to fill before invoking this 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?
Schema description coverage is 100%, and each parameter is already well documented with examples, defaults, bounds, and guidance. The tool description itself does not add extra parameter semantics, but because the schema carries the full burden, the baseline of 3 is appropriate.
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 exactly what the tool returns: raw normalized XBRL facts for one company, newest first, with a concrete list of fields. It also distinguishes itself from company_financials, which provides clean annual statements and ratios. This leaves no ambiguity about the tool's role among its siblings.
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?
The description explicitly tells when to use this tool: 'for individual reported values, quarterly figures or filing provenance.' It also names the alternative, company_financials, and the condition for choosing it instead, making the routing decision explicit. The schema param description further advises calling lookup_company first when only a ticker or name is available.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SEC filing index for one company, newest first: form, filing date, report period, accession number, 8-K item codes and a direct sec.gov document_url. Use it to find or cite a specific 10-K, 10-Q, 8-K or Form 4; use company_facts or company_financials for the numbers in the filings. Cost: $0.005 per call; unpaid calls return a payment-required error.
| Name | Required | Description | Default |
|---|---|---|---|
| cik | Yes | SEC Central Index Key (CIK), e.g. 320193 for Apple. Only have a ticker or company name? Call lookup_company first (free). | |
| form | No | Form type to return, as SEC names it, e.g. 10-K, 10-Q, 8-K, 4; omit for every form. | |
| limit | No | Maximum filings to return, newest first; up to 2000. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the cost per call ($0.005), the payment-required error for unpaid calls, the newest-first ordering, and the direct sec.gov document_url. It does not describe pagination or rate limits, but the output schema likely covers the return shape. No contradiction with annotations.
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?
The description is compact and front-loaded: the first sentence states what the tool returns and the ordering; the second sentence gives usage guidance and alternatives; the third sentence discloses cost and error behavior. Every sentence earns its place, and the cost/error note is placed at the end where it doesn't obscure the primary purpose.
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 read-only, idempotent list tool with a rich output schema and 100% parameter documentation, the description is complete. It covers what the tool returns, how to use it, when to use alternatives, how to resolve a ticker to a CIK, and the cost/error condition. An agent has everything needed to select and invoke this tool 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 the schema already documents all three parameters. The description adds meaning beyond the schema by explaining the purpose of the returned fields (form, filing date, report period, accession number, 8-K item codes, document_url) and by clarifying the 'form' parameter's SEC naming convention with examples. The cik parameter description also adds a practical routing hint to lookup_company. This exceeds the baseline 3 for full schema coverage.
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 ('find or cite'), a precise resource ('SEC filing index for one company'), and the exact output fields (form, filing date, report period, accession number, 8-K item codes, document_url). It also names the sibling tools it is not (company_facts, company_financials), so an agent can distinguish it from the other company_* tools without opening schemas.
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?
The description explicitly says when to use this tool ('to find or cite a specific 10-K, 10-Q, 8-K or Form 4') and when to use alternatives ('use company_facts or company_financials for the numbers in the filings'). It also gives a concrete routing hint in the cik parameter description ('Only have a ticker or company name? Call lookup_company first'). This is explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Annual financial statements for one company, one row per fiscal year: income statement, balance sheet and cash flow lines plus ratios (gross_margin, operating_margin, roe, roa, fcf, debt_to_equity, ...). Use it for a known company's history; use company_facts for individual reported values and quarterly periods, compare_to_peers to benchmark it against its industry, and screen_companies to find companies by criteria. Cost: $0.02 per call; unpaid calls return a payment-required error.
| Name | Required | Description | Default |
|---|---|---|---|
| cik | Yes | SEC Central Index Key (CIK), e.g. 320193 for Apple. Only have a ticker or company name? Call lookup_company first (free). | |
| fy_to | No | Last fiscal year to include; omit to end at the latest year on file. | |
| fy_from | No | First fiscal year to include, e.g. 2020; omit to start at the earliest year on file. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, lowering the burden on the description. The description adds useful behavioral context beyond annotations by noting the row-per-fiscal-year structure, the $0.02 cost, and the payment-required error for unpaid calls, which helps agents anticipate failures.
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?
The description is compact and front-loaded: it first states what the tool returns, then gives usage routing to siblings, and ends with cost and error behavior. Every sentence adds distinct value, and no filler or redundancy is present.
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?
Given the tool has a rich output schema and annotations covering read-only behavior, the description covers the key context an agent needs: scope, granularity, alternative tools, cost, and a failure mode. No critical information appears missing for correct tool selection and invocation.
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 the input schema already documents cik, fy_to, and fy_from with examples and suggested usage. The description itself adds little parameter-level meaning, but since the schema handles it well, the baseline score of 3 is appropriate.
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 clearly states the tool returns annual financial statements for one company, one row per fiscal year, including income statement, balance sheet, cash flow, and ratios. It distinguishes itself from siblings by naming company_facts, compare_to_peers, and screen_companies, so an agent can immediately tell what this tool is for.
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?
The description explicitly says to use this tool for a known company's history and directs the agent to company_facts for individual reported values and quarterly periods, compare_to_peers for industry benchmarking, and screen_companies for finding companies by criteria. This is clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Composite factor scorecard for one company: quality (Piotroski, Altman, accruals), value (owner-earnings DCF), insider conviction (Form 4 buying as bps of market cap), institutional positioning (13F) and short sentiment, each 0-100, plus a renormalized composite_score and coverage (the share of factors present). Also returns institutional ownership %, insider buy intensity, short-to-ADV and governance flags (Form 4 latency, Item 4.02 restatements, stale fundamentals). Use top_signals to rank every company by the same composite. RESEARCH SIGNAL, NOT INVESTMENT ADVICE. Cost: $0.05 per call; unpaid calls return a payment-required error.
| Name | Required | Description | Default |
|---|---|---|---|
| cik | Yes | SEC Central Index Key (CIK), e.g. 320193 for Apple. Only have a ticker or company name? Call lookup_company first (free). | |
| weights | No | Optional JSON object of factor weights, e.g. {"quality":0.4,"value":0.4}. Factors: quality, value, insider, institutional and sentiment; each defaults to 0.2, and unknown keys or negative weights are ignored. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds valuable context: it is a research signal, not investment advice, costs $0.05 per call, and returns a payment-required error when unpaid. It also discloses the renormalization of composite_score and the inclusion of governance flags, going beyond what annotations convey.
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?
The description is long but every sentence carries distinct information: output composition, factor categories, derived metrics, alternative tool, disclaimer, and cost. It is front-loaded with the core purpose and structured so an agent can quickly extract behavior, alternatives, and constraints.
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?
Given the tool's complexity and the presence of an output schema, the description covers the purpose, output contents, factor weighting behavior, alternative tool, cost, and error condition. An agent has sufficient context to invoke the tool correctly and interpret its results without missing critical details.
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%, with detailed parameter descriptions for both cik and weights, including defaults, factor names, and behavior for invalid keys. The description itself does not add parameter-level meaning beyond the schema, so the baseline score of 3 is appropriate.
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 clearly states the tool is a composite factor scorecard for one company, enumerating the specific factor categories and output components. It also distinguishes itself from top_signals by noting that tool is used to rank every company, leaving no ambiguity about the tool's scope.
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?
It explicitly names top_signals as the alternative for ranking companies, which helps an agent choose between single-company scoring and cross-company ranking. It does not enumerate all possible exclusions, but the single-company focus and sibling differentiation provide clear enough guidance for typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One company's metrics for a fiscal year next to its industry cohort: the percentiles of every metric for each revenue size bucket in its 2-digit SIC group. Use it to judge whether a company's margins, returns or leverage are above or below sector norms; use industry_aggregate for a cohort without a specific company. Cost: $0.05 per call; unpaid calls return a payment-required error.
| Name | Required | Description | Default |
|---|---|---|---|
| fy | Yes | Fiscal year to compare, e.g. 2025. | |
| cik | Yes | SEC Central Index Key (CIK), e.g. 320193 for Apple. Only have a ticker or company name? Call lookup_company first (free). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the call as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond that: the cost per call, the payment-required error for unpaid calls, and the specific grouping/revenue-bucket behavior. No contradiction with annotations.
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?
The description is compact and front-loaded: it opens with what the tool returns, then gives the use case and alternative, then the cost/error caveat. Every sentence earns its place and none are redundant.
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 read-only comparison tool with a rich output schema and full parameter documentation, the description covers the core behavior, use case, alternative tool, and a critical payment constraint. Nothing needed to invoke it correctly is missing.
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 the baseline is 3. The description reinforces that the tool compares a company's metrics for a fiscal year, but it does not add materially new meaning to the cik or fy parameters beyond what the schema already provides.
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 ('One company's metrics for a fiscal year'), the comparison target ('its industry cohort'), and the actual content ('percentiles of every metric for each revenue size bucket in its 2-digit SIC group'). It also explicitly distinguishes itself from the sibling industry_aggregate, so an agent can select it correctly.
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?
It states the intended use case ('judge whether a company's margins, returns or leverage are above or below sector norms') and names the alternative for a different need ('use industry_aggregate for a cohort without a specific company'). This is explicit when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Benchmark percentiles (p10, p25, median, p75, p90, plus mean and company count n) for one financial metric, per fiscal year, 2-digit SIC industry group and revenue size bucket. Use it for questions like "what is the median gross margin of large software companies?"; use compare_to_peers to place one company in its cohort and market_insight (sector_landscape) for margin medians across every industry. Cost: $0.05 per call; unpaid calls return a payment-required error.
| Name | Required | Description | Default |
|---|---|---|---|
| fy | No | Fiscal year; omit for every year, newest first. | |
| size | No | Revenue size bucket: micro (under 10M USD), small (10M+), mid (100M+), large (1B+) or mega (10B+); omit for every bucket. | |
| metric | Yes | Metric to benchmark, e.g. gross_margin, operating_margin, net_margin, roe, roa, debt_to_equity, current_ratio, rd_intensity, revenue, fcf. | |
| industry | No | 2-digit SIC industry group, e.g. 73 (business services, including software); omit for every industry. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the cost per call ($0.05), the payment-required error for unpaid calls, and the exact output structure (p10, p25, median, p75, p90, mean, company count). It doesn't describe pagination or rate limits, but the output schema covers return values.
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?
The description is compact and front-loaded: it states the output structure first, then gives usage examples, then names alternatives, then discloses cost. Every sentence earns its place, and the cost disclosure is placed at the end where it doesn't distract from the core purpose.
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 read-only, idempotent benchmark tool with a rich output schema and 100% parameter documentation, the description is complete. It covers what the tool returns, when to use it, when not to use it (via sibling routing), and the cost/error behavior. Nothing an agent needs to call it correctly is missing.
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 the schema already documents all four parameters. The description adds a few examples of metric values (gross_margin, operating_margin, etc.) and clarifies the size bucket thresholds (micro under 10M USD, small 10M+, etc.) in the schema. However, the description itself doesn't add much beyond what the schema provides, so baseline 3 is appropriate.
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 ('benchmark'), a precise resource (percentiles for one financial metric per fiscal year, 2-digit SIC industry group, and revenue size bucket), and names the exact percentile values returned. It clearly distinguishes itself from siblings by naming compare_to_peers and market_insight as alternatives for different questions.
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?
The description gives explicit when-to-use guidance with example questions ('what is the median gross margin of large software companies?') and explicitly names alternatives (compare_to_peers for placing one company in its cohort, market_insight for margin medians across every industry). It also discloses the cost and payment-required error behavior, which is critical usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insider (Form 4) transactions for one company over the trailing months, plus a summary: open-market buys vs sales, distinct buyers and net dollar value, with 10b5-1 plan flags. Cluster buying by officers and directors is a studied positive signal. Use company_signal for insider conviction scored alongside other factors. Not investment advice. Cost: $0.02 per call; unpaid calls return a payment-required error.
| Name | Required | Description | Default |
|---|---|---|---|
| cik | Yes | SEC Central Index Key (CIK), e.g. 320193 for Apple. Only have a ticker or company name? Call lookup_company first (free). | |
| months | No | Trailing window in months, 1-60. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable context beyond that: cost per call, the payment-required error behavior for unpaid calls, the analytical meaning of cluster buying, and a disclaimer that it is not investment advice.
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?
The description is compact and front-loaded, starting with the core deliverable and then adding the signal context, routing advice, disclaimer, and cost/error behavior. Every sentence contributes useful information without fluff.
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 a detailed description, complete parameter documentation, and an output schema present, nothing essential is missing for correct invocation. Cost, error handling, prerequisite lookup, and alternative routing are all covered.
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 both cik and months are already well documented. The description does not add much parameter-level detail beyond reinforcing the trailing-month window, so the baseline of 3 is appropriate.
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 exactly what the tool provides: Form 4 insider transactions for a single company over a trailing window, with a summary of open-market buys vs sales, distinct buyers, net dollar value, and 10b5-1 plan flags. It clearly distinguishes itself from company_signal by framing that tool as the scored-conviction alternative.
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?
The description explicitly routes the agent to company_signal when scored insider conviction is needed, and the parameter description tells users to call lookup_company first if they only have a ticker or name. This provides clear when-to-use and when-to-use-alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
13F institutional ownership snapshot for one company: number of holders, aggregate shares and value, and quarter-over-quarter change (accumulating vs trimming). 13F filings lag the quarter by up to 45 days and show long positions only. Use company_signal for institutional positioning scored alongside other factors. Not investment advice. Cost: $0.02 per call; unpaid calls return a payment-required error.
| Name | Required | Description | Default |
|---|---|---|---|
| cik | Yes | SEC Central Index Key (CIK), e.g. 320193 for Apple. Only have a ticker or company name? Call lookup_company first (free). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: 13F filings lag the quarter by up to 45 days, show long positions only, and cost $0.02 per call with a payment-required error for unpaid calls. This is exactly the kind of real-world caveat an agent needs.
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 sentences, each earning its place: what the tool returns, the data caveat, the sibling alternative, and the cost/error condition. The core purpose is front-loaded, and the guidance is compact.
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 single-parameter read-only tool with a full output schema, the description covers the data returned, the timing caveat, the alternative tool, the prerequisite lookup, and the cost/error behavior. Nothing an agent needs to decide whether to call it is missing.
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 the schema already documents the cik parameter fully, including an example (320193 for Apple) and a pointer to lookup_company. The description doesn't add parameter-level detail beyond that, but it doesn't need to. Baseline 3 is appropriate.
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 ('snapshot') and resource ('13F institutional ownership for one company'), and enumerates the exact data points returned (number of holders, aggregate shares/value, QoQ change). It also distinguishes itself from company_signal, a sibling that scores institutional positioning alongside other factors, so an agent can tell them apart.
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?
The description explicitly says when to use this tool (for a 13F snapshot) and when not to (use company_signal for institutional positioning scored alongside other factors). It also gives a concrete prerequisite: if you only have a ticker or company name, call lookup_company first. This is clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Catalog of the curated market-wide analyses: each one's name, path, description, parameters with defaults, and price. Call it before market_insight or standard_score to choose an analysis and its parameters. Free: no API key or payment needed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the description adds value beyond them by disclosing that the tool is free and requires no API key or payment. It also clarifies the tool surfaces analysis parameters and defaults, which is useful behavioral context not present in the annotations.
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?
Three short sentences cover purpose, content, usage timing, and cost. The most important information is front-loaded, and every sentence adds value without 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?
For a zero-parameter read-only catalog tool with an output schema, the description is fully sufficient. It tells the agent when to call it, what it will receive, and the access requirements, leaving no critical gaps.
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 has zero parameters and the input schema is empty, so there is nothing for the description to explain about arguments. With 0 params, baseline is 4; the description appropriately focuses on what the tool returns rather than parameters.
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 clearly identifies the resource ('catalog of curated market-wide analyses') and states the content exactly: name, path, description, parameters with defaults, and price. It also relates itself to siblings by saying it should be called before market_insight or standard_score, so an agent can distinguish it from those 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?
The description gives explicit usage direction: 'Call it before market_insight or standard_score to choose an analysis and its parameters.' It also provides cost/authentication guidance ('Free: no API key or payment needed'), which helps the agent decide when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a company's SEC CIK from its ticker, CIK or name. Every company tool takes a cik, so call this first when you only have a ticker (AAPL) or a name (apple). Returns up to limit matches, best first (exact ticker, exact CIK, name prefix, name contains; within each, companies with tickers before other filers such as individuals), each with cik, name, tickers, sic and sic_description; no match is an empty list, not an error. Free: no API key or payment needed.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum matches to return, 1-25. | |
| query | Yes | A ticker (AAPL, BRK.B), CIK digits (320193), or all or part of a company name (apple); 1-100 characters. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description adds substantial behavioral context: match ordering ('exact ticker, exact CIK, name prefix, name contains'), entity priority ('companies with tickers before other filers such as individuals'), empty-result behavior ('no match is an empty list, not an error'), and accessibility ('no API key or payment needed'). It contradicts nothing in the annotations.
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?
The description is front-loaded with the core purpose, then uses compact parentheticals to encode the matching priority and return fields. Each sentence contributes either usage guidance, result semantics, or operational context; there is no filler.
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 simple lookup tool with only two parameters, the description plus schema fully covers input formats, result selection, ordering, empty results, output fields, and free access. An agent can correctly decide to call it and interpret its response without additional documentation.
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 100%, so the baseline is 3. The description adds value by explaining how the query is ranked and interpreted into exact vs prefix vs contains matches, and how the limit applies to the returned ordering. This goes beyond the schema's basic type and length descriptions.
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 opens with a specific verb and resource: 'Find a company's SEC CIK from its ticker, CIK or name.' It also distinguishes this tool from the sibling data tools by stating that every company tool takes a CIK, so this lookup is the prerequisite step.
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?
It gives clear context by saying 'call this first when you only have a ticker (AAPL) or a name (apple).' It does not explicitly name a sibling alternative or state 'do not use when you already have a CIK,' but that exclusion is strongly implied by the CIK prerequisite framing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Curated analysis computed live across all US public companies, chosen by name: top_companies (rank by a metric, optionally within an industry), movers (largest change in a metric between fy_from and fy_to), sector_landscape (margin medians per industry), metric_trend (yearly sum, median or mean of a metric), capital_returns (buybacks vs dividends by size bucket) or filing_velocity (monthly filing counts for a form type). Each parameter's description says which analyses read it; the response reports the fiscal year(s) used. Use screen_companies for your own criteria and standard_score for F-Score, Z-Score and similar scores. Cost: $0.15 per call; unpaid calls return a payment-required error.
| Name | Required | Description | Default |
|---|---|---|---|
| fy | No | Fiscal year for top_companies, sector_landscape and capital_returns, and the default end year for movers and metric_trend; omit for the current fiscal year. | |
| agg | No | metric_trend only: sum (the default), median or mean. | |
| form | No | filing_velocity only: form type to count, e.g. 8-K (the default). | |
| name | Yes | Analysis to run: top_companies, movers, sector_landscape, metric_trend, capital_returns or filing_velocity. | |
| fy_to | No | End year for movers and metric_trend (default fy). | |
| limit | No | Maximum rows for top_companies and movers, 1-200 (default 25). | |
| metric | No | Metric for top_companies, movers and metric_trend, e.g. revenue (the default), gross_margin, research_development. | |
| months | No | filing_velocity only: months of history, default 18, up to 120. | |
| fy_from | No | Start year for movers (default fy - 2) and metric_trend (default 2015). | |
| industry | No | top_companies only: 2-digit SIC industry group, e.g. 73; omit for every industry. | |
| min_revenue | No | Minimum annual revenue in USD for movers (default 1e9) and sector_landscape (default 1e8). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the description's job is lighter. It adds useful non-annotation behavior: analyses are computed live, the response reports the fiscal year(s) used, calls cost $0.15, and unpaid calls return a payment-required error.
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?
The description is front-loaded with the core purpose, then the analysis list, then routing and cost. Three sentences cover a complex 11-parameter tool without redundancy or filler.
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?
Given the full input schema, output schema, and safety annotations, the description covers what the tool does, which mode to choose, which alternatives to use, what the response reports, and the cost/error condition. An agent has enough to select and invoke 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 coverage is 100%, so the baseline is 3. The description adds value by defining each named analysis in terms of the parameters that drive it (metric, industry, fy_from/fy_to, form, months, agg), which helps an agent select the right parameter combination per mode.
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 tool's resource ('all US public companies'), states the operation ('computed live'), and enumerates six selectable analyses by name, so an agent immediately knows what market_insight returns. It also distinguishes this tool from screen_companies and standard_score, which are the closest sibling alternatives.
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?
It explicitly routes to alternatives: 'Use screen_companies for your own criteria and standard_score for F-Score, Z-Score and similar scores.' It also clarifies the paid nature and failure mode, which is important before invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Screen US public companies for one fiscal year by financial criteria and return the matches with their name, tickers, industry and metrics, largest revenue first. Use it to discover companies; use company_financials for one known company's history and industry_aggregate for cohort benchmarks. Cost: $0.10 per call; unpaid calls return a payment-required error.
| Name | Required | Description | Default |
|---|---|---|---|
| fy | Yes | Fiscal year to screen, e.g. 2025. | |
| limit | No | Maximum companies to return, largest revenue first; up to 500. | |
| filters | Yes | JSON list of [metric, op, value] triples that must all hold, e.g. [["gross_margin",">",0.6],["revenue",">",1e9]]. op is >, >=, <, <= or =; value is a number; up to 8 triples (more are ignored). An unknown metric returns an error listing the valid ones. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the $0.10 per call cost, the payment-required error on unpaid calls, and the fact that unknown metrics return an error listing valid ones. It doesn't detail pagination or exact return shape, but the output schema exists and the added cost/error behavior goes beyond annotations.
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?
The description is compact and front-loaded: it states the core function first, then the output ordering, then the routing guidance, then the cost/error note. Every sentence earns its place, and the cost warning is a critical operational detail that is placed at the end without bloating the description.
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 screening tool with a rich input schema, output schema, and comprehensive annotations, the description covers the essential operational context: what it returns, how results are ordered, when to use alternatives, and the cost/error behavior. Nothing an agent needs to decide whether to call this tool is missing.
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 the schema already documents all three parameters. The description adds context about the filters format (JSON list of triples, up to 8, unknown metric error) and the limit default/ordering, but these are also largely in the schema. Baseline 3 is appropriate because the schema carries the heavy lifting and the description doesn't add significant new parameter meaning beyond what's already there.
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 ('Screen'), a resource ('US public companies'), a scope ('one fiscal year'), and the output ordering ('largest revenue first'). It also names sibling tools (company_financials, industry_aggregate) to distinguish itself, making it clear what this tool is for.
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?
The description explicitly says when to use this tool ('Use it to discover companies') and when to use alternatives ('use company_financials for one known company's history and industry_aggregate for cohort benchmarks'). This is direct routing guidance with no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Short-selling pressure for one company: the FINRA daily short-volume ratio (short volume / total volume) over about 20 trading days, a bearish-sentiment proxy. This is daily short-sale volume, not bi-monthly short interest. Use company_signal for short sentiment scored alongside other factors. Not investment advice. Cost: $0.02 per call; unpaid calls return a payment-required error.
| Name | Required | Description | Default |
|---|---|---|---|
| cik | Yes | SEC Central Index Key (CIK), e.g. 320193 for Apple. Only have a ticker or company name? Call lookup_company first (free). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety profile is well covered. Description adds behavioral context beyond annotations: it clarifies data source (FINRA daily short-volume ratio), time window (~20 trading days), and billing behavior (cost $0.02 per call; unpaid calls return a payment-required error). This goes beyond the annotation set.
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 concise sentences with distinct purposes: definition, disambiguation from short interest, alternative routing, and billing note. Zero filler, important caveats front-loaded.
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?
Complete for a read-only single-parameter tool: describes data source, time window, meaning, alternative, prerequisite lookup, billing, and error condition. Output schema exists, so return value documentation is not the description's job. No unresolved gaps.
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 100%, so the baseline is 3. The description adds value by explaining the cik parameter's format and providing a concrete example (320193 for Apple), plus routing guidance (call lookup_company first if only ticker/name). This enriches the schema documentation without repeating it.
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?
Description states a specific verb-resource pair: measures short-selling pressure for one company via FINRA daily short-volume ratio over ~20 trading days as a bearish-sentiment proxy. It also distinguishes itself from the related concept of short interest explicitly, though not from sibling tools by name.
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?
Provides clear context for when to use this tool (when needing short-sale volume ratio over ~20 days, as a sentiment proxy) and explicitly recommends company_signal for short sentiment scored alongside other factors. It also notes non-investment-advice and billing prerequisites (cost per call, payment-required errors). Lacks explicit when-not-to-use or alternative distinctions beyond company_signal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Academic fundamental scores across US public companies, chosen by name: piotroski (F-Score 0-9, financial strength), altman_z (bankruptcy-risk zones), beneish_m (elevated M-Score: an accounting-quality screen, not evidence of manipulation), magic_formula (Greenblatt rank on earnings yield and return on capital) or accruals (Sloan earnings quality). Each company is scored on its own latest fiscal year (fiscal_year per row); fy selects the cohort whose latest scored year is fy -- it does not re-score companies on an earlier year. Use company_signal for one company's quality, value and sentiment factors together. Peer-reviewed formulas; not investment advice. Cost: $0.15 per call; unpaid calls return a payment-required error.
| Name | Required | Description | Default |
|---|---|---|---|
| fy | No | Cohort to return: companies whose latest scored fiscal year is fy (they are not re-scored on an earlier year). Omit for every company on its own latest year. A year no company is scored on returns an error listing the available years. | |
| name | Yes | Score to rank by: piotroski, altman_z, beneish_m, magic_formula or accruals. | |
| zone | No | altman_z only: safe, grey or distress; omit for every zone, most distressed first. | |
| limit | No | Maximum companies to return, 1-200. | |
| worst | No | accruals only: true ranks the highest accrual ratios (lowest earnings quality) first; omit or false ranks the lowest first. | |
| min_score | No | piotroski only: minimum F-Score, 0-9; omit for 7. | |
| min_revenue | No | Minimum annual revenue in USD, e.g. 1e9. | |
| flagged_only | No | beneish_m only: omit or true for elevated M-Scores only; false for every score. | |
| exclude_foreign | No | Exclude foreign private issuers (20-F filers); set false to include them. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavior beyond that: fy selects the cohort but does NOT re-score companies, each row carries its own fiscal_year, beneish_m is 'an accounting-quality screen, not evidence of manipulation,' and the call costs $0.15 with a payment-required failure mode. Nothing contradicts the annotations.
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?
Roughly 135 words for a 9-parameter tool with 16 siblings — every clause earns its place and the core purpose is front-loaded. The score-type glossary, fy clarification, and cost disclosure are all functional, though the dense paragraph could be slightly restructured for easier scanning.
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?
An output schema exists and parameter coverage is 100%, so the description needn't document return values or parameter formats — yet it still adds the missing glue: what each score means, the cohort/fiscal-year semantics, the alternative routing, and the cost/failure mode. An agent has everything needed to invoke the tool 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 coverage is 100% so the baseline is 3, and the description clearly adds value above the schema: it glosses each name value (what an F-Score of 0-9 means, what altman_z zones indicate, why an elevated M-Score is not proof of manipulation) and reinforces fy's cohort semantics. It doesn't elaborate on the remaining eight parameters, but the schema already documents those thoroughly.
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?
Opens with a specific verb and resource — 'Academic fundamental scores across US public companies' — and enumerates all five scoring models (piotroski, altman_z, beneish_m, magic_formula, accruals) with one-line meanings (F-Score 0-9, bankruptcy-risk zones, Greenblatt rank, Sloan earnings quality). It also names the sibling company_signal as the alternative for single-company composite analysis, so an agent can select the right tool without opening schemas.
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 an explicit when-to-use: cohort-level fundamental scoring of US public companies, selected by model name. It gives an explicit when-not and alternative: 'Use company_signal for one company's quality, value and sentiment factors together.' The fy clarification also prevents the common misuse of expecting companies to be re-scored on earlier fiscal years.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank US public companies by composite factor score (quality, value, insider, institutional and short-sentiment factors, each 0-100), highest first, with each company's factor scores, coverage, and restatement and stale-fundamentals flags. Use company_signal for one company's full scorecard. RESEARCH SIGNAL, NOT INVESTMENT ADVICE. Cost: $0.25 per call; unpaid calls return a payment-required error.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum companies to return, 1-200. | |
| weights | No | Optional JSON object of factor weights, e.g. {"quality":0.4,"value":0.4}. Factors: quality, value, insider, institutional and sentiment; each defaults to 0.2, and unknown keys or negative weights are ignored. | |
| min_coverage | No | Minimum share of the five factors a company must be scored on, 0-1 (0.6 means at least 3 of 5). | |
| min_composite | No | Minimum composite score, 0-100. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds genuinely useful behavioral context: sort order, factor score ranges, included flags, and the $0.25-per-call cost with a payment-required error for unpaid calls.
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?
The description is compact and front-loaded with the ranking behavior, then adds sibling routing, a disclaimer, and cost in order of importance. Every sentence earns its place with no tautology or fluff.
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 ranked-list tool with an output schema and comprehensive parameter schema, the description covers the ranking logic, result contents, payment behavior, and the main sibling alternative. Nothing needed for correct invocation is missing.
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?
Input schema coverage is 100%, with each parameter already described in detail. The description adds context about factor definitions and score ranges but doesn't need to restate parameter semantics; the schema carries the burden, so baseline 3 is appropriate.
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 ('Rank'), a resource ('US public companies'), and the exact ranking basis ('composite factor score') with factor details. It explicitly distinguishes itself from company_signal by naming the sibling, leaving no ambiguity about what this tool does.
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?
It gives clear guidance to use company_signal when a single company's full scorecard is needed, which routes agents away from this tool in that case. It does not discuss other ranking/screening siblings like screen_companies, but the core alternative is covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
buffett_scan6 fields changedInput schema / properties / exclude_foreign / descriptionAdded value: +"Exclude foreign private issuers (20-F filers); set false to include them."Input schema / properties / fy / descriptionAdded value: +"Fiscal year of the published Quality Scores; omit for the latest. A year that isn't published returns an error listing the published years."Input schema / properties / industry / descriptionAdded value: +"2-digit SIC industry group, e.g. 73 (business services, including software); omit for every industry."Input schema / properties / limit / descriptionAdded value: +"Maximum companies to return, 1-200."Input schema / properties / min_revenue / descriptionAdded value: +"Minimum annual revenue in USD, e.g. 1e9."Input schema / properties / min_score / descriptionAdded value: +"Minimum Quality Score, 0-100."buffett_value7 fields changedInput schema / properties / exclude_foreign / descriptionAdded value: +"Exclude foreign private issuers (20-F filers); set false to include them."Input schema / properties / fy / descriptionAdded value: +"Fiscal year of the published Quality Scores; omit for the latest. A year that isn't published returns an error listing the published years."Input schema / properties / industry / descriptionAdded value: +"2-digit SIC industry group, e.g. 73 (business services, including software); omit for every industry."Input schema / properties / limit / descriptionAdded value: +"Maximum companies to return, 1-200."Input schema / properties / min_margin_of_safety / descriptionAdded value: +"Minimum DCF margin of safety (1 - market cap / intrinsic value), e.g. 0.2 for a price 20% below intrinsic value; 0 keeps companies at or below intrinsic value."Input schema / properties / min_revenue / descriptionAdded value: +"Minimum annual revenue in USD, e.g. 1e9."Input schema / properties / min_score / descriptionAdded value: +"Minimum combined_score (the mean of the quality and value scores), 0-100."company_facts4 fields changedInput schema / properties / cik / descriptionAdded value: +"SEC Central Index Key (CIK), e.g. 320193 for Apple. Only have a ticker or company name? Call lookup_company first (free)."Input schema / properties / concept / descriptionAdded value: +"Canonical concept to return, e.g. revenue, net_income, total_assets, operating_cash_flow; omit for every concept."Input schema / properties / fy_from / descriptionAdded value: +"Earliest fiscal year to include, by each filing's own fiscal-year tag (fiscal_year in the rows); omit for every year."Input schema / properties / limit / descriptionAdded value: +"Maximum facts to return, newest first; up to 20000."company_filings3 fields changedInput schema / properties / cik / descriptionAdded value: +"SEC Central Index Key (CIK), e.g. 320193 for Apple. Only have a ticker or company name? Call lookup_company first (free)."Input schema / properties / form / descriptionAdded value: +"Form type to return, as SEC names it, e.g. 10-K, 10-Q, 8-K, 4; omit for every form."Input schema / properties / limit / descriptionAdded value: +"Maximum filings to return, newest first; up to 2000."company_financials3 fields changedInput schema / properties / cik / descriptionAdded value: +"SEC Central Index Key (CIK), e.g. 320193 for Apple. Only have a ticker or company name? Call lookup_company first (free)."Input schema / properties / fy_from / descriptionAdded value: +"First fiscal year to include, e.g. 2020; omit to start at the earliest year on file."Input schema / properties / fy_to / descriptionAdded value: +"Last fiscal year to include; omit to end at the latest year on file."company_signal2 fields changedInput schema / properties / cik / descriptionAdded value: +"SEC Central Index Key (CIK), e.g. 320193 for Apple. Only have a ticker or company name? Call lookup_company first (free)."Input schema / properties / weights / descriptionAdded value: +"Optional JSON object of factor weights, e.g. {\"quality\":0.4,\"value\":0.4}. Factors: quality, value, insider, institutional and sentiment; each defaults to 0.2, and unknown keys or negative weights are ignored."compare_to_peers2 fields changedInput schema / properties / cik / descriptionAdded value: +"SEC Central Index Key (CIK), e.g. 320193 for Apple. Only have a ticker or company name? Call lookup_company first (free)."Input schema / properties / fy / descriptionAdded value: +"Fiscal year to compare, e.g. 2025."industry_aggregate4 fields changedInput schema / properties / fy / descriptionAdded value: +"Fiscal year; omit for every year, newest first."Input schema / properties / industry / descriptionAdded value: +"2-digit SIC industry group, e.g. 73 (business services, including software); omit for every industry."Input schema / properties / metric / descriptionAdded value: +"Metric to benchmark, e.g. gross_margin, operating_margin, net_margin, roe, roa, debt_to_equity, current_ratio, rd_intensity, revenue, fcf."Input schema / properties / size / descriptionAdded value: +"Revenue size bucket: micro (under 10M USD), small (10M+), mid (100M+), large (1B+) or mega (10B+); omit for every bucket."insider_activity2 fields changedInput schema / properties / cik / descriptionAdded value: +"SEC Central Index Key (CIK), e.g. 320193 for Apple. Only have a ticker or company name? Call lookup_company first (free)."Input schema / properties / months / descriptionAdded value: +"Trailing window in months, 1-60."institutional_ownership1 field changedInput schema / properties / cik / descriptionAdded value: +"SEC Central Index Key (CIK), e.g. 320193 for Apple. Only have a ticker or company name? Call lookup_company first (free)."lookup_companymarket_insight11 fields changedInput schema / properties / agg / descriptionAdded value: +"metric_trend only: sum (the default), median or mean."Input schema / properties / form / descriptionAdded value: +"filing_velocity only: form type to count, e.g. 8-K (the default)."Input schema / properties / fy / descriptionAdded value: +"Fiscal year for top_companies, sector_landscape and capital_returns, and the default end year for movers and metric_trend; omit for the current fiscal year."Input schema / properties / fy_from / descriptionAdded value: +"Start year for movers (default fy - 2) and metric_trend (default 2015)."Input schema / properties / fy_to / descriptionAdded value: +"End year for movers and metric_trend (default fy)."Input schema / properties / industry / descriptionAdded value: +"top_companies only: 2-digit SIC industry group, e.g. 73; omit for every industry."Input schema / properties / limit / descriptionAdded value: +"Maximum rows for top_companies and movers, 1-200 (default 25)."Input schema / properties / metric / descriptionAdded value: +"Metric for top_companies, movers and metric_trend, e.g. revenue (the default), gross_margin, research_development."Input schema / properties / min_revenue / descriptionAdded value: +"Minimum annual revenue in USD for movers (default 1e9) and sector_landscape (default 1e8)."Input schema / properties / months / descriptionAdded value: +"filing_velocity only: months of history, default 18, up to 120."Input schema / properties / name / descriptionAdded value: +"Analysis to run: top_companies, movers, sector_landscape, metric_trend, capital_returns or filing_velocity."screen_companies3 fields changedInput schema / properties / filters / descriptionAdded value: +"JSON list of [metric, op, value] triples that must all hold, e.g. [[\"gross_margin\",\">\",0.6],[\"revenue\",\">\",1e9]]. op is >, >=, <, <= or =; value is a number; up to 8 triples (more are ignored). An unknown metric returns an error listing the valid ones."Input schema / properties / fy / descriptionAdded value: +"Fiscal year to screen, e.g. 2025."Input schema / properties / limit / descriptionAdded value: +"Maximum companies to return, largest revenue first; up to 500."short_pressure1 field changedInput schema / properties / cik / descriptionAdded value: +"SEC Central Index Key (CIK), e.g. 320193 for Apple. Only have a ticker or company name? Call lookup_company first (free)."standard_score9 fields changedInput schema / properties / exclude_foreign / descriptionAdded value: +"Exclude foreign private issuers (20-F filers); set false to include them."Input schema / properties / flagged_only / descriptionAdded value: +"beneish_m only: omit or true for elevated M-Scores only; false for every score."Input schema / properties / fy / descriptionAdded value: +"Cohort to return: companies whose latest scored fiscal year is fy (they are not re-scored on an earlier year). Omit for every company on its own latest year. A year no company is scored on returns an error listing the available years."Input schema / properties / limit / descriptionAdded value: +"Maximum companies to return, 1-200."Input schema / properties / min_revenue / descriptionAdded value: +"Minimum annual revenue in USD, e.g. 1e9."Input schema / properties / min_score / descriptionAdded value: +"piotroski only: minimum F-Score, 0-9; omit for 7."Input schema / properties / name / descriptionAdded value: +"Score to rank by: piotroski, altman_z, beneish_m, magic_formula or accruals."Input schema / properties / worst / descriptionAdded value: +"accruals only: true ranks the highest accrual ratios (lowest earnings quality) first; omit or false ranks the lowest first."Input schema / properties / zone / descriptionAdded value: +"altman_z only: safe, grey or distress; omit for every zone, most distressed first."top_signals4 fields changedInput schema / properties / limit / descriptionAdded value: +"Maximum companies to return, 1-200."Input schema / properties / min_composite / descriptionAdded value: +"Minimum composite score, 0-100."Input schema / properties / min_coverage / descriptionAdded value: +"Minimum share of the five factors a company must be scored on, 0-1 (0.6 means at least 3 of 5)."Input schema / properties / weights / descriptionAdded value: +"Optional JSON object of factor weights, e.g. {\"quality\":0.4,\"value\":0.4}. Factors: quality, value, insider, institutional and sentiment; each defaults to 0.2, and unknown keys or negative weights are ignored."standard_score1 field changedInput schema / properties / fyAdded value: +{
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Fy"
+}buffett_scan3 fields changedInput schema / properties / fy / anyOfAdded value: +[
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / fy / defaultPrevious value: -2025New value: +nullInput schema / properties / fy / typeRemoved value: -"integer"buffett_value3 fields changedInput schema / properties / fy / anyOfAdded value: +[
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / fy / defaultPrevious value: -2025New value: +nullInput schema / properties / fy / typeRemoved value: -"integer"company_signaltop_signalsinsider_activityinstitutional_ownershipshort_pressurebuffett_scanbuffett_valuecompany_factscompany_filingscompany_financialscompare_to_peersindustry_aggregatelist_insightsmarket_insightscreen_companiesstandard_scoreSEC EDGAR fundamentals as agent tools: look up or screen US public companies. Free, no key, CC0.
SEC filing intelligence for AI agents. Financials, screening, peer comparison for 5,000+ companies.
SEC EDGAR financials, insider trading, and economic data for AI agents. US GAAP + IFRS.
Point-in-time, survivorship-free SEC EDGAR fundamentals + smart-money signals for AI agents.
Add one secure layer between your agents and this server.
