aether-developer

financial_search

Read-onlyIdempotent

Search SEC filings (10-K, 10-Q, 8-K, registration statements/prospectuses and press exhibits; S&P 500 coverage, ~10 years) with hybrid semantic + keyword retrieval. TWO MODES. Search mode (pass query): results ranked by relevance, highest first. FETCH MODE (omit query): no ranking at all — pass an issuer plus any of form_type / fiscal_year / accession_number / section and get that filing's sections back in filing-date-desc then document order, in tens of milliseconds. Use fetch when you already know WHICH document you want and only need its text. ALWAYS pass issuer (ticker, cik or company_name) — the company the question is about — plus fiscal_year and/or form_type when you know them. Scoped calls are fast and precise. A call with no issuer runs as scope=cross_company: slower, ranked by relevance only, and the response sets quality_caveat — check for that field. Use scope=cross_company deliberately only for questions that are genuinely about many companies ("which filers name NVIDIA as a supplier"). Built for agents: every hit is a ready-to-cite payload — exact filing-section text, form type, filing date, accession-numbered citation, source URL and a 0-1 confidence score — no HTML parsing, no EDGAR pagination. Use for revenue/segment figures, risk factors, M&A and contract terms, customer/supplier concentration, and any claim that must trace to a primary source. Fetch mode pages: pass the response's next_offset as offset to read past limit. Returned windows overlap; counts of a term over returned text are not document counts. partial: true means retrieval degraded; an empty result is then not proof of absence. Coverage is NOT US-only: Sweden/Bolagsverket, Japan/EDINET, Korea/DART annual reports are included. Those issuers have no US ticker — pass issuer.company_name (e.g. "Sivers Semiconductors", "Samsung Electronics", "Ajinomoto") or scope a whole market with jurisdiction (["SE"], ["JP"], ["KR"]).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "financial_search"
  }
}

Input Schema

Name	Required	Description	Default
`cik`	No	Exact SEC CIK values to scope retrieval. Values are normalized to 10 digits.
`limit`	No
`query`	No	Natural language search query. OMIT IT for fetch mode: with no query nothing is embedded or scored and the matching sections come back in filing-date-desc then document order. Fetch mode requires an identifier (issuer.ticker / issuer.cik / issuer.company_name / cik[] / accession_number) — a query-less call without one is rejected.
`scope`	No	issuer (default): results limited to the resolved company. cross_company: search all filers — for questions like "who names NVIDIA as a supplier". Cross-company results are slower, relevance-ranked only, and always carry `quality_caveat`.	issuer
`domain`	No	public_equity = single-company filing search; supply_chain = cross-company supplier/customer relationship evidence; auto (default) = detect from the query.	auto
`fields`	No
`issuer`	No	The company the question is about. Pass at least one of ticker (e.g. "NVDA"), cik (e.g. "1045810"), or company_name (required for non-US issuers, which have no US ticker). Scopes retrieval to that filer: fast and precise. Strongly recommended on every call, and REQUIRED in fetch mode.
`offset`	No	Fetch mode only: paging cursor. Omit (or 0) for the first page, then pass the previous response's `next_offset` until it is absent. Opaque: it counts chunk rows, not results.
`profile`	No	Retrieval profile. `hybrid` (default) ranks by the engine's own fused score (saturated lexical + vector cosine), highest first. `bm25` is the lexical-only fallback. `hybrid_rerank` and `hybrid_rerank_tickerprior` are accepted as aliases of `hybrid` for one release — the cross-encoder they named was removed on 2026-09-11.	hybrid
`section`	No	Filing section(s), matched case-insensitively as a substring of the stored label — "Item 1A" matches "Item 1A. Risk Factors". In fetch mode this is how you ask for one part of a filing.
`form_type`	No	Only return these filing forms, for example ["20-F"] or ["6-K"].
`fiscal_year`	No	Issuer's fiscal year as the company labels it (NVIDIA FY2027 = year ending Jan 2027). Resolved from XBRL DEI fiscal-year focus where available, else from the issuer's fiscal year-end; an empty year widens ±1 with a caveat.
`jurisdiction`	No	Scope to non-US issuer jurisdictions (ISO-3166 alpha-2): "SE" (Sweden/Bolagsverket), "JP" (Japan/EDINET), "KR" (Korea/DART). These carry no US ticker and are otherwise buried by SEC-centric ranking. US filings have an empty jurisdiction tag, so this filter is for non-US scoping only — omit it to include US (the default). A named non-US issuer surfaces even without this filter, via the company-name anchor.
`prefer_recent`	No	Prefer newer filings when relevance scores are close. Automatically enabled for latest/current/guidance queries.
`return_format`	No	Response shape. 'section' (default) returns the full SEC section the matching chunk belongs to. 'chunk' returns the matching window only. 'both' returns both.	section
`accession_number`	No	Exact SEC accession number. When set, retrieval is hard-scoped to that filing.
`exclude_form_type`	No	Exclude filing forms. Company searches already suppress fund/proxy forms by default.

Output Schema

Name	Required	Description
`mode`	Yes	"search" = ranked by relevance. "fetch" = no ranking; sections listed in filing-date-desc then document order, and `total` is the number of matching chunks.
`query`	Yes
`scope`	No	Effective scope after issuer resolution.
`total`	Yes
`domain`	Yes
`source`	Yes
`partial`	No	True when retrieval degraded (e.g. lexical-only because the semantic arm was unavailable). A short or empty result is then not proof of absence.
`results`	Yes
`latency_ms`	Yes
`next_offset`	No	Fetch mode: more rows exist; pass this as `offset` for the next page. Absent on the last page.
`partial_reason`	No
`quality_caveat`	No	Present when the result is not issuer-precise. Read it before trusting cross-company results.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 10, 2026

addedInput schema / properties / offset

Added value: +{
+  "description": "Fetch mode only: paging cursor. Omit (or 0) for the first page, then pass the previous response's `next_offset` until it is absent. Opaque: it counts chunk rows, not results.",
+  "minimum": 0,
+  "type": "integer"
+}

addedOutput schema / properties / next_offset

Added value: +{
+  "description": "Fetch mode: more rows exist; pass this as `offset` for the next page. Absent on the last page.",
+  "type": "integer"
+}

addedOutput schema / properties / partial

Added value: +{
+  "description": "True when retrieval degraded (e.g. lexical-only because the semantic arm was unavailable). A short or empty result is then not proof of absence.",
+  "type": "boolean"
+}

addedOutput schema / properties / partial_reason
```
Added value: +{
+  "type": "string"
+}
```

First observedSep 11, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantially more: fetch-mode latency in tens of milliseconds, the `quality_caveat` field on cross-company responses, `partial: true` meaning degraded retrieval, overlapping returned windows, and non-US coverage sources. These are behavioral traits an agent needs that no annotation or schema conveys.

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?

Mode selection, issuer requirement and caveats are front-loaded, so the structure serves the reader. It is nonetheless long and repetitive for a 17-parameter tool, restating the issuer requirement and the `quality_caveat` consequence more than once.

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

Completeness5/5

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

An output schema exists, so return values need no prose, and annotations carry the safety profile. What remains for the description — mode semantics, scoping tradeoffs, degradation signals, pagination and coverage limits — is all present, leaving nothing an agent needs missing for a 17-parameter retrieval tool.

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

Parameters4/5

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

Schema coverage is 88%, so the baseline is 3, but the description adds real meaning beyond it: `issuer` as the mandatory anchor for non-US filers, `offset`/`next_offset` paging chain, `jurisdiction` for issuer markets without US tickers, and section labels matched as substrings. Some of this duplicates the schema text, which keeps it out of the top score.

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

Purpose5/5

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

States a specific verb and resource (search SEC filings, hybrid semantic + keyword retrieval) and enumerates the covered form types and coverage window. It also explicitly defines the two operating modes, which lets an agent distinguish this from transcript_search and regulation_search without opening a schema.

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

Usage Guidelines5/5

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

Gives explicit routing rules: use search mode with `query` for relevance ranking, use fetch mode when you already know which document you want, always pass `issuer`, and reserve scope=cross_company for questions genuinely spanning many companies. It names the failure condition (query-less call without an identifier is rejected) and the caveat that follows an unscoped call.

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

All aether-developer tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.