Official economic statistics, company filings, earnings calls and market data - extracted from first party sources, with sources cited.
Scored across 14 tools
The six search_* tools target clearly distinct corpora (datasets, series, filings, transcripts, media, news), and the retrieval tools (get_series, run_sql, get_geo_data, get_market_data) are differentiated by data type. The main overlap is search_datasets vs search_series (both about finding data by title), which could be confused despite the descriptions clarifying scope (across schemas vs within one schema).
All 14 tools use consistent snake_case verb_noun form (describe_dataset, get_series, search_news, run_sql, send_feedback). The verb families (get_/search_/describe_) map cleanly to their purpose with no convention mixing.
14 tools is well within the sweet spot and each earns its place across discovery, retrieval, domain-specific search, style, and feedback. No redundant or filler tools are apparent.
The surface covers the full read-only lifecycle: catalog/discovery (get_data_catalog, search_datasets, search_series, describe_dataset), retrieval (get_series, run_sql, get_geo_data, get_market_data), domain corpora (filings, transcripts, media, news), plus style guides and feedback. No obvious dead ends for a read-only analytics platform.
Full metadata for one dataset: topic, methodology, discontinuities,
any base-change notice, plus the live dimensions and example series.
Call after search_datasets narrows you to a dataset.
| Name | Required | Description | Default |
|---|---|---|---|
| schema | Yes | ||
| dataset_code | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, which is an unusual combination for what appears to be a metadata-read tool. The description does not reconcile this apparent contradiction or explain why a 'describe' operation would not be read-only. With annotations covering some behavioral traits but in a way that conflicts with the tool's apparent purpose, the description needed to clarify the write-like or stateful behavior, and it does not.
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 two sentences, front-loaded with the resource and the content returned, followed by a sequencing instruction. Every phrase earns its place with 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?
An output schema exists, so the description need not explain return values, and it correctly summarizes the key returned content. However, for a two-required-parameter tool with 0% parameter coverage and anomalous annotations (readOnlyHint=false on a describe operation), the description leaves important gaps about what 'schema' means and why the tool is not read-only.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the two required parameters ('schema' and 'dataset_code') are completely undocumented in both the schema and the description. The description implies the tool operates on 'one dataset' but never explains what 'schema' means (e.g., database schema or dataset schema namespace) or how to obtain valid values. The description must compensate for the coverage gap and fails to do so.
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 (describe) and resource (one dataset) and lists the content returned (topic, methodology, discontinuities, base-change notice, live dimensions, example series). It does not explicitly differentiate itself from siblings like get_series or search_datasets beyond the implicit reference in the call-order instruction, so it is clear but lacks full sibling differentiation.
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 provides explicit sequencing guidance: 'Call after search_datasets narrows you to a dataset.' This tells the agent when to use the tool in relation to one sibling. However, it does not state when NOT to use it or name alternatives for retrieving series-level data (e.g., get_series), leaving some conditions implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the data sources FactIQ has, plus the shared table structure.
Call this once before exploring. Returns the visible schemas (organization +
country), the ones with no data loaded yet (schemas_without_data — skip
them), a per-schema dataset index, and the shared DDL for the series,
data_points, dimensions and compound_series tables.
schemas: optional comma-separated filter (e.g. "bls,bea"). full: heavy per-dataset descriptions instead of the compact index.
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | ||
| schemas | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and idempotentHint=false, implying a state-mutating, non-repeatable call, while the description presents a pure one-shot listing/read ("Call this once before exploring... Returns the visible schemas..."). The mismatch will confuse an agent about side effects and cacheability; the description itself adds useful context (cheap vs. `full` mode, empty schemas) but does not resolve the conflict.
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?
Front-loaded purpose in sentence one, behavior/return content next, and parameter notes last; every sentence carries information and nothing is 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?
Both parameters, the one-shot calling pattern, and the shape of the response are covered even though an output schema exists, leaving little ambiguity for a 2-parameter catalog tool. The only real gap is that it does not address the annotation signals about mutability and idempotency.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden and does so well: `schemas` is documented as an optional comma-separated filter with a concrete example ("bls,bea"), and `full` is explained as heavier per-dataset descriptions instead of the compact index, clarifying the default trade-off.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: "List the data sources FactIQ has, plus the shared table structure," and enumerates what comes back (visible schemas, dataset index, shared DDL). It is clearly distinguishable from siblings like describe_dataset and search_datasets, though it never names them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Call this once before exploring" gives an explicit calling condition and timing, and the note to skip `schemas_without_data` tells the agent how to act on the result. It stops short of naming alternatives or stating when not to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get satellite-derived indicators aggregated over a country, one state/province, or a bounding box. Use for fires, emissions-based activity, rainfall, vegetation, temperature, and soil-moisture questions.
For a sub-national area, call one state/province at a time. Informal regions such as "north India" or "the Midwest" have no boundary, so cover them with one call per state or a bounding box; using the whole country answers a different question. Grid cells and fire detections are activity snapshots, never fire perimeters. For ndvi_s2 and *_tropomi grids, drop or flag cells with low valid_obs_share. Results include units, source attribution, and caveats; cite the attribution. External-provider calls can take about 30 seconds, and rainfall or grid calls can take longer.
| Name | Required | Description | Default |
|---|---|---|---|
| region | Yes | Region as an ISO3 code or country name ("IND" or "India"); "Country/State" or "ISO3/State" ("India/Punjab" or "CHN/Guangdong") for a state/province; or "bbox:west,south,east,north" in degrees. State/province boundaries are available for IND, CHN, IDN, VNM, THA, MYS, PHL, PAK, BGD, LKA, MMR, KHM, NPL, KOR, JPN, TWN, and USA. | |
| dataset | Yes | Satellite dataset. One of: - "fires_viirs": active fire detections and fire radiative power (NASA FIRMS, 2012->, one day behind). Covers crop-residue burning, forest fires, and flaring. - "no2_tropomi": tropospheric NO2 column (Sentinel-5P, 2018->, ~3 days), an industrial/traffic activity proxy. Check valid_obs_share; cloudy intervals below 0.2 are weakly supported. - "so2_tropomi": SO2 column (Sentinel-5P, 2018->, ~3 days) for coal power, smelting, refining, and volcanoes. Noisy away from strong sources; track trends rather than absolute background levels. - "co_tropomi": CO column (Sentinel-5P, 2018->, ~3 days) for biomass/crop burning and industrial combustion. CO drifts across borders and is seasonal, so compare the same season across years. - "aerosol_index_tropomi": UV aerosol index (Sentinel-5P, 2018->, ~3 days) for smoke, dust, and haze. It is dimensionless; sustained values above ~1 indicate heavy smoke or dust, and it works over clouds. - "ndvi_s2": cloud-masked vegetation NDVI (Sentinel-2, 2017->, ~2-5 days), a crop-condition signal. Check valid_obs_share and compare the same season across years. - "precip_chirps": gauge-calibrated rainfall (CHIRPS, 1981->, ~2 days, 50S-50N) for monsoon, drought, and flood risk. - "precip_imerg": rainfall totals (NASA IMERG V07 Late, 2000->, ~1-2 days, global at 0.1 degree). Use where CHIRPS has no coverage; daily and monthly values are rainfall totals. - "temperature_power": mean/max/min 2m air temperature (NASA POWER, 1981->, ~3 days) for heatwaves and energy demand. - "soil_moisture_power": root-zone soil wetness from 0 to 1 (NASA POWER, 1981->, ~3 days) for agricultural drought. - "wind_power": 10m wind speed, daily maximum, eastward and northward components, the direction the wind blows from, and a 0-1 steadiness score (NASA POWER, 1981->, ~3 days). Use it to separate weather from emission changes in air-pollution data and to trace where smoke comes from. - "humidity_power": 2m relative humidity in % (NASA POWER, 1981->, ~3 days), a weather control for haze and fine particles. | |
| end_date | Yes | Inclusive end date in ISO YYYY-MM-DD format. | |
| resolution | No | Optional fires_viirs grid-cell size in degrees when aggregation="grid"; one of 0.005, 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, or 5. Omit it to choose a size automatically from the region. Values finer than 0.1 read individual detections and return the 500 busiest cells. Not accepted by other datasets or aggregation modes. | |
| start_date | Yes | Inclusive start date in ISO YYYY-MM-DD format. | |
| aggregation | No | Aggregation mode. "monthly" (default) or "daily" returns a time series. Most datasets allow at most 50 intervals per call (~4 years monthly or ~7 weeks daily); fires_viirs allows 200 (~16 years monthly or ~7 months daily). fires_viirs, ndvi_s2, and *_tropomi also accept "grid": one spatial row per lat/lon cell over the whole window, at most 500 rows, with a 92-day maximum window (366 days for fires). fires_viirs also accepts "seasons", which repeats the requested calendar window in every year since 2012 and returns one row per year, and "points", which returns exact detections only when the window contains at most 500; otherwise use grid or narrow the window. | monthly |
| include_flares | No | fires_viirs only. False by default, excluding gas flares, other permanent industrial heat sources, volcanoes, and offshore detections so only vegetation fires are counted. Set true over a gas field or to count every detection NASA publishes. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover safety profile only (readOnlyHint=false, openWorldHint=true, destructedHint=false), leaving the description to carry operational behavior — and it does: ~30s latency for external providers, longer for rainfall/grid calls, returned units/attribution/caveats, and the requirement to cite attribution. It also discloses an interpretation hazard ('grid cells and fire detections are activity snapshots, never fire perimeters') and a data-quality rule for low valid_obs_share.
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 tight paragraphs, front-loaded with purpose, then the sub-national rule, then data caveats and latency. Sentence-level density is high and little is filler, though the caveat block could be trimmed slightly without losing signal.
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 7-parameter, open-world data retrieval tool with an output schema already documenting return shape, the description supplies everything else an agent needs: scope granularity, latency expectations, attribution obligations, and interpretation caveats. Nothing material is left for the agent to guess.
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, and the description adds genuine meaning on top: the one-state-per-call constraint for the region parameter, the informal-region workaround, and the pointer to filter low valid_obs_share for ndvi_s2 and *_tropomi grids. It does not restate dataset/resolution syntax, which the schema already handles well.
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+resource ('Get satellite-derived indicators') and pins down the aggregation scope (country, state/province, or bounding box), which is more precise than the title 'Get satellite data'. It does not explicitly name competing siblings (search_datasets, get_series, run_sql), though the domain is narrow enough that an agent can separate it by subject matter alone.
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 names the question types the tool answers ('fires, emissions-based activity, rainfall, vegetation, temperature, and soil-moisture questions') and gives explicit operational rules: one state/province per call for sub-national areas, bounding boxes for informal regions, and the warning that 'using the whole country answers a different question.' The exclusion of borderless informal regions is exactly the kind of when-not guidance that prevents misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent market data the warehouse lags on: quotes, OHLCV, company profiles, FX, and commodities.
Set data_type to price_history for stocks, currency pairs, and commodities; the asset format determines which market is queried. Use search_company_filings for financial statements and reported facts.
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | Ticker, currency pair, commodity, or company-search text. Examples: "AAPL", "EUR/USD", "WTI", "Brent", "NVIDIA". | |
| limit | No | Maximum number of historical price rows to request. | |
| data_type | No | The market or profile data to return. | price_history |
| frequency | No | Price-history frequency. Defaults to daily. | daily |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description frames this purely as retrieval ("Get market data", "Recent market data the warehouse lags on") and never mentions mutation, yet the annotations declare readOnlyHint=false and idempotentHint=false. The description therefore contradicts the declared behavior profile rather than complementing it, which is the exact failure mode the rubric scores as 1.
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 sentences, front-loaded with the resource and its contents, then the data_type selection rule, then the sibling alternative. Every sentence carries information, though the middle sentence is dense enough that it could be split for scanability.
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 full schema description coverage, an output schema covering return values, and only four parameters, the description supplies the missing pieces an agent needs: what data comes back, how to choose data_type per asset class, and which sibling handles filings. Its only gap is the unresolved conflict with the read-only annotation.
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 genuinely adds meaning beyond the enum: the asset format selects which market is queried, and price_history is the right data_type for stocks, currency pairs, and commodities. It does not explain the interaction between limit/frequency, but those are already documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Get market data") and enumerates the exact content classes returned: quotes, OHLCV, company profiles, FX, and commodities. It also draws a boundary against a named sibling, routing financial statements and reported facts to search_company_filings, so an agent can distinguish it without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete routing guidance — "Set data_type to price_history for stocks, currency pairs, and commodities" and the note that the asset format determines which market is queried — plus one explicit alternative (search_company_filings for financial statements). It stops short of stating when-not-to-use relative to other siblings such as get_series or search_news.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one series' data: timeseries, tabular, or COMPOUND:: all work.
Returns title, units, frequency, notes and data points, with source metadata.
transform="yoy_pct" (percent change) or "yoy_diff" (difference, for rates)
adds a column with the change versus the same period one year earlier,
matched by calendar date — use it for inflation or growth from one series
instead of a LAG(value, 12) query, which goes wrong after any missing
month. The cell is null where the prior-year period is absent, and
transform.periods_without_prior lists those periods.
If the result carries a coverage_note, the series has periods with no
observation (listed in missing_periods): say so in the answer, leave them
blank rather than interpolating, and label any aggregate that spans them
as partial.
SEC-backed results include row_sources keyed by result_index; each entry
identifies the supporting filing, accession/form/publication date, whether
the observation is reported or derived, and its standardized source_link.
Cite that row's source URL beside any figure and label derived observations
as derived. A document-precision link does not open an exact passage.
IMF (imf schema) results also carry projections_start_after (the last
year the IMF counts as actual; later years are IMF staff projections),
release_label (the IMF publication, e.g. "Fiscal Monitor (October
2026)") and, when either is known, a projection_note. Say which years
are projections when you use them. Both fields are null when the IMF
gives no such fact for the series.
At most 50 points come back; if the series is longer the result is flagged
"truncated": true — narrow it with from_year/to_year, or pull the series
through run_sql with an aggregation (e.g. monthly/quarterly via
date_trunc) rather than trying to fetch every point.
| Name | Required | Description | Default |
|---|---|---|---|
| schema | Yes | ||
| to_year | No | ||
| from_year | No | ||
| series_id | Yes | ||
| transform | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description describes a pure read ('Fetch one series' data', returns points, adds columns, flags truncation), but the annotations declare readOnlyHint=false and idempotentHint=false, i.e. a non-read-only, non-idempotent operation. That is a direct conflict between the two sources of truth, and the rubric assigns 1 for a contradiction regardless of the otherwise rich behavioural detail.
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?
Long, but front-loaded with the core fetch semantics and each subsequent block (transform semantics, coverage notes, SEC row sources, IMF projections, truncation) is operational rather than filler. Still dense enough that an agent must read several sentences before the truncation limit and its workaround appear.
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?
Though an output schema exists, the description goes further and explains the fields that matter for correct downstream use: `coverage_note`/`missing_periods`, `row_sources`/`result_index` citation duties, IMF `projections_start_after`/`release_label`, and the 50-point truncation flag. Nothing an agent needs in order 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 0%, so the description has to carry the load and largely does: it enumerates the legitimate `transform` values (`yoy_pct`, `yoy_diff`), explains what each computes and how prior periods are matched, and gives the purpose of `from_year`/`to_year` (narrowing a truncated series). It adds nothing for the two required params (`schema`, `series_id`), which is the remaining gap.
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+resource ('Fetch one series' data') and immediately scopes what formats are supported (timeseries, tabular, COMPOUND). Between 'fetch one series' vs 'search_series' vs pulling via 'run_sql', the agent can tell this apart from every sibling 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes around alternatives: use transform instead of a `LAG(value, 12)` query, and if the result is truncated use `from_year`/`to_year` or pull through `run_sql` with an aggregation. It never states when to choose `get_series` over `search_series` (discovery vs retrieval), so it is clear context but not a full decision rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch FactIQ's house-style authoring guides so anything you build matches FactIQ's conventions and look. Call this before producing a chart, a report, or written analysis from FactIQ data, and follow what it returns. By default, use FactIQ's style for all FactIQ work unless the user asks otherwise.
You can fetch several at once. Pass any combination of:
"chart" — how to build and style a FactIQ chart: which chart type, finding- style titles, data hygiene, the FactIQ colour palette and plot surface, and sourcing
"report" — report structure, voice, and per-chart sourcing
"sql" — query idioms and pitfalls for FactIQ's tables
"earnings" — quoting discipline, spoken-vs-filed sourcing, guidance tables, and claim-verification patterns for anything built from search_earnings_transcripts
"all" — every guide
Returns each requested guide's markdown text, keyed by name. This is free — it does not count against your tool quota.
| Name | Required | Description | Default |
|---|---|---|---|
| guides | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds genuinely useful context beyond the annotations: it returns markdown keyed by guide name, several guides can be fetched in one call, and it is free (no tool-quota cost). One tension: the description frames this as a pure fetch/read, while the annotations declare readOnlyHint=false, which an agent may read as 'may mutate state' – worth noting but not a positive claim of a write, so not a hard contradiction.
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?
Front-loads purpose and the when-to-call rule, then uses a scannable bullet list for the option values and closes with return shape and cost. The length is justified by the five documented guide types; no sentence is 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?
An output schema exists, yet the description still helpfully notes the return is markdown keyed by name. Combined with the exhaustive value list and the usage trigger, an agent has everything needed 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 description coverage is 0% and the single 'guides' array has no enum, so the description carries the full burden – and it does, enumerating all five valid values ('chart', 'report', 'sql', 'earnings', 'all') with what each contains. This is exactly the compensation the low coverage requires.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetch FactIQ's house-style authoring guides') and makes the intent unmistakable. It is the only style-guide tool among siblings, so there is no ambiguity with describe_dataset, get_data_catalog, or the search_* 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?
Explicitly says when to call it ('Call this before producing a chart, a report, or written analysis from FactIQ data') and what the default behavior is ('use FactIQ's style for all FactIQ work unless the user asks otherwise'). The 'earnings' guide is even routed to its sibling source, search_earnings_transcripts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a read-only SELECT against the FactIQ data warehouse, scoped to one schema — the power tool for joins, pivots and aggregation.
Read-only role, 30s statement timeout, with FactIQ's query transforms and
series-metadata enrichment. Resolve ids from series before filtering
data_points. auto_retry=true opts into a server-side reviser on zero
rows. See the factiq://guide/sql resource.
Returns at most 50 rows. If the query matches more, the result is flagged
"truncated": true — that is your cue to aggregate or compute in SQL
(GROUP BY, date_trunc, a SUM/AVG/rank/ratio) and return that, NOT to try
to fetch the raw rows. A chart or a summary needs the aggregated result, and
large raw results don't fit in context anyway.
Year-over-year and other period comparisons must join on the calendar
period (date_trunc('month', prior.time) = date_trunc('month', cur.time) - interval '1 year' — the stored day of the month varies by source, so never
compare exact dates), never on a row offset such as
LAG(value, 12) OVER (ORDER BY time): a series with one missing month
compares the wrong periods for the twelve rows after the gap (LEAD: the
twelve before it) and the numbers still look plausible. For one series prefer get_series with transform. When
the result carries a coverage_note, the rows have periods with no
observation (listed in missing_periods, per series): name them in the
answer, do not interpolate, and label any aggregate that spans them as
partial.
page is the one exception and works only on the nasa_fires schema, where
a row is a single fire detection that belongs to no series and so cannot be
aggregated into one. Each page holds 50 rows; the answer carries page and
has_more, and you read the next block with page=2, page=3 and so on.
Give the query an ORDER BY, otherwise Postgres may return the same row on
two pages and never return another. Still prefer a count or a total when
that answers the question — paging through thousands of detections does not.
Runs through FactIQ's read-only database role, which rejects any attempt to modify data (INSERT/UPDATE/DELETE/DROP/…).
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| page | No | ||
| schema | Yes | ||
| explore | No | ||
| question | No | ||
| auto_retry | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the tool is strictly read-only ('Run a read-only SELECT', 'runs through FactIQ's read-only database role, which rejects any attempt to modify data'), but the annotations declare readOnlyHint=false, which asserts the tool is not read-only. This is a direct conflict on a safety-critical property and is exactly the kind of mismatch an agent could act on. Despite otherwise rich disclosure (30s timeout, 50-row cap, truncation flag, coverage_note semantics), the rule for a contradiction applies.
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?
Dense but front-loaded: capability, limits, and output semantics come before the paging exception. Nearly every sentence carries operative detail (limits, join syntax, ordering requirement), though the paging discussion runs long relative to its narrow scope and could be tightened.
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, yet the description still usefully explains the `truncated`, `coverage_note`, `missing_periods`, `page` and `has_more` return semantics an agent must reason about. Combined with the timeout and read-only role disclosure, it is close to complete for a complex query tool; only the `explore` and `question` parameters are left unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry parameter meaning, and it does for four of six: `sql` as SELECT-only, `schema` as single-schema scoping, `page` restricted to `nasa_fires` with 50 rows per page and an ORDER BY requirement, and `auto_retry` as a server-side reviser on zero rows. `explore` and `question` are never explained, which is the remaining gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Run a read-only SELECT against the FactIQ data warehouse, scoped to one schema') plus the capability envelope ('joins, pivots and aggregation'). It distinguishes itself from siblings by explicitly routing single-series work to `get_series` and by naming the one schema (`nasa_fires`) where paging applies.
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 explicit when-to-use rules and when-not rules: prefer aggregation over fetching raw rows when `truncated` is set, prefer `get_series` with `transform` for a single series, and use `page` only on `nasa_fires`. It even supplies the correct join pattern for YoY comparisons and forbids the tempting `LAG` alternative with the reason why.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This is FactIQ's central tool for company filings. It searches structured facts and report metadata from one company's filed reports, for every company in the filings store: US SEC filers (10-K, 10-Q, 8-K, plus 20-F, 40-F, 6-K for foreign filers) and companies listed in Germany, the UK, France and Switzerland (annual, half-year, Q1, and Q3 reports; for example company="BAS" for BASF SE from German issuer reports in EUR, company="ULVR" for Unilever plc from the FCA National Storage Mechanism, company="MC.PA" for LVMH from the AMF via info-financiere.gouv.fr, and company="NESN" for Nestlé from the reports on the company's own website; UK values are in the issuer's reporting currency, GBP, USD or EUR, French values in EUR, and Swiss values in the issuer's reporting currency, CHF, USD or EUR). A UK, French or Swiss company whose symbol is also a US ticker is stored with its exchange suffix (.L London, .PA Paris, .SW Zurich); the bare symbol goes to the SEC filer, so company="MC" is Moelis & Company and company="MC.PA" is LVMH. It also covers the Nifty 50 companies listed in India, from the quarterly financial results they file with the National Stock Exchange (Q1 to Q4; the Q4 results also carry the audited full-year figures; values in INR; for example company="RELIANCE" for Reliance Industries). It also covers large companies listed in Japan, from the securities reports they file on EDINET, and in South Korea, from the business reports they file on DART (annual, half-year, Q1, and Q3 reports; values in JPY or KRW as filed; for example company="7203.T" for Toyota Motor and company="005930.KS" for Samsung Electronics). The search is deterministic and does not call a language model. Every successful response is a tree and does not expose database row IDs. Set format="json" for the structured tree field. Set format="pretty" for only a human-readable rendered_tree text. The two formats are never returned together. JSON filing and fact nodes retain source_url and add a standardized source_link object for the original filing/report; the pretty rendering ends with a "Source documents" list mapping each cited filing to its URL. When using a returned figure, place its source URL beside the claim as a Markdown link, for example: FY2025 revenue was $40.0B (Visa Inc. FY2025 10-K). A sources line that names the filing without linking its URL is not sufficient. Do not make a second call solely to find a citation or substitute a related press release. source_precision="document" means the URL opens the source document, not an exact passage.
Use an exact ticker when possible. A company name is accepted only when it identifies one issuer. A share-class sibling ticker resolves to the same SEC filer (for example GOOGL resolves to the stored GOOG). If a ticker has several exact matches, possible_matches lists every tied company and its identifiers. When nothing matches, possible_matches lists the closest stored companies. When a bare ticker resolves to one company and other companies are stored under that ticker plus an exchange suffix (MC resolves to Moelis & Company; MC.PA is LVMH), the result is still the bare-ticker company and possible_matches lists the suffixed companies.
concept selects one registered financial concept and returns it over time. For example, concept="revenue" selects the best revenue concept stored for that company. The response states the selected concept. Use query instead for a broad search across several concepts.
search_target controls the tree content. coverage shows available report types and dates. filings shows report records and source URLs. metrics shows available concepts, dimensions, units, and period coverage. facts shows reported numeric values. An empty facts browse is filing-first. A facts search with query or concept is concept-first so that values across reporting periods stay together.
commentary and risk_changes return qualitative statements extracted from SEC filings when each filing was processed; every statement carries a verbatim quote from the filing. commentary returns management's explanatory statements from MD&A sections and earnings press releases: growth drivers, demand and pricing commentary, capacity and execution milestones, strategy changes, and vaguely quantified statements such as "grew mid-teens" with a numeric range attached. risk_changes returns year-over-year changes in the stated risk factors of annual reports (Item 1A or Item 3.D): new, modified, and removed risks, with the changed passage quoted. A period with no risk_changes rows means the risk factors were unchanged from the prior year or that filing is not yet processed — never that the company reported no risks. Both targets cover US SEC filers only; commentary and risk_changes remain SEC-only and return no rows for German, UK, French, Swiss, Indian, Japanese, or Korean issuer reports.
query searches concept names, source labels, source codes, XBRL concepts, aliases, definitions, and segment names. For commentary and risk_changes it searches topics, statements, and quotes. Filters are applied before search. report_type accepts a common report type (annual, quarterly, half_year) or a source form such as 10-K or 10-Q. For German, UK, and French filers, quarterly covers the Q1, half-year, and Q3 reports; their source forms are the document codes of the source (FCA ACS, FR, IR; AMF AMF-RFA, AMF-RFS, AMF-IT, AMF-URD, AMF-RES). An Indian company files no separate annual report: its Q4 results hold the audited full-year statements. For Indian filers, quarterly covers the Q1, Q2, and Q3 results plus the fourth-quarter values of the Q4 results; annual covers the Q4 results; the source forms are "Financial Results" and "Integrated Filing (Financials)". fiscal_period="FY" returns the full-year values of the Q4 results. For Japanese and Korean filers, quarterly covers the Q1, half-year, and Q3 reports. Japan ended the quarterly securities report for quarters that start on or after 1 April 2024, so later Japanese periods have no Q1 or Q3 report. The Korean source forms are the DART report codes 11011 (annual), 11012 (half-year), 11013 (Q1), and 11014 (Q3). fiscal_year and fiscal_period accept company reporting labels such as 2026 and Q3. Earnings 8-Ks take their quarter from the 10-Q or 10-K whose period ended within the 80 days before the 8-K, and keep the 8-K filing date as the reported date. A freshly announced 8-K whose periodic filing has not arrived yet carries a quarter estimated from the company's fiscal calendar, replaced by the exact period when the filing lands. If neither is available, the tool omits the fiscal label instead of guessing.
Some companies file the same concept twice for one period and segment — for example a gross segment total next to a net-of-eliminations figure. Both are served: the extra line is its own series node whose name ends in "(reported line 2)", and its evidence_note says so. The two lines are alternative statements of the same item. Never add a "reported line 2" series to its ordinary counterpart — that double-counts.
For non-admin callers, active_only is always enforced by the tool endpoint. With active_only enabled, every target is limited to facts currently marked active and serving; coverage and filings omit reports with no such facts.
If an exact-ticker metrics or facts request has no matching serving data, the tool falls back to Twelve Data standardized consolidated statements. A resolved issuer listed in Germany, the UK, France, Switzerland, India, Japan, or South Korea is sent to the vendor with its exchange suffix (.DE, .L, .PA, .SW, .NS, .T, .KS, .KQ) appended to a bare stored ticker; a stored ticker that already carries the suffix (MC.PA, RELIANCE.NS, 7203.T, 005930.KS) is sent as is, and the bare symbol (RELIANCE, 7203) is sent with the stored suffix. Company names and bare tickers without a resolved issuer remain filings-database-only so vendor data cannot be attributed to a different issuer with the same ticker. A request that names no report_type or fiscal_period tries quarterly statements and then annual, so annual-only vendor coverage still answers. A concept the filings database already holds is never answered from the vendor, even when the other filters leave no rows. Fallback values carry no filing-document, source-page, or segment evidence. coverage, filings, and segment-filtered requests remain filings-database-only.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum matched rows before tree grouping. For facts, each numeric observation is one row, so one series with many periods uses many rows — filter by period, metric class, or segment instead of raising the limit. The range is 1 to 50 and the default is 20. For coverage, it limits the latest filing records. | |
| query | No | Broad lexical search across concept names, labels, codes, aliases, definitions, and segment names. For commentary and risk_changes it searches statement topics, summaries, and verbatim quotes. It applies to every target except coverage. Normally leave it empty when concept is set. | |
| format | No | Response form for a successful tree result. json returns only the JSON tree. pretty returns only readable rendered_tree text. The forms are never combined. | json |
| company | Yes | Required company identifier. Use an exact ticker, full company name, LEI, or another stored identifier. A share-class sibling ticker such as GOOGL resolves to the same SEC filer as the stored GOOG. A company listed in Germany, the UK, France, or Switzerland resolves by its local ticker (BAS for BASF SE, ULVR for Unilever plc, MC.PA for LVMH, NESN for Nestlé), full name, or LEI. When a UK, French or Swiss symbol is also a US ticker, the company is stored with its exchange suffix (.L London, .PA Paris, .SW Zurich: MC.PA, BA.L, ROP.SW) and the bare symbol (MC, BA, ROP) goes to the SEC filer; the response then lists the suffixed company under possible_matches. A Nifty 50 company listed in India resolves by its NSE symbol (RELIANCE, M&M), the same symbol with .NS, its BSE scrip code, or its full name. A company listed in Japan or South Korea resolves by its stock code with the exchange suffix (7203.T for Toyota Motor, 005930.KS for Samsung Electronics, .KQ for KOSDAQ), the bare stock code (7203, 005930), its EDINET or DART code, or its full name. A tied ticker match returns every possible company instead of selecting one. | |
| concept | No | One requested metric, such as Revenue. The tool selects the best stored concept for this company, reports what it selected, and returns that concept across periods. Valid only for metrics or facts. | |
| date_to | No | Optional inclusive latest period-end date for filings, metrics, or facts. | |
| segment | No | Optional case-insensitive filter for a business segment, product, region, dimension member, dimension axis, or source label. It applies to metrics and facts. | |
| date_from | No | Optional inclusive earliest period-end date for filings, metrics, or facts. | |
| active_only | No | Return only current serving facts. This is always enforced for non-admin users; admins may set false to inspect inactive rows. When true, coverage and filings also omit reports with no serving facts. | |
| fiscal_year | No | Optional company fiscal-year label, such as 2026. It applies to filings, metrics, and facts. For metrics and facts it selects the fiscal year of the period a value covers, even when a later report stated the value. | |
| report_type | No | Optional report filter for every target except coverage. Accepts a common type such as annual, quarterly, or half_year, or a source form such as 10-K or 10-Q (or a source document code such as ACS, FR, IR, AMF-RFA, AMF-RES). For German, UK, and French filers, quarterly covers Q1, half-year, and Q3 reports. For Indian filers, quarterly covers the Q1, Q2, and Q3 results, and annual covers the Q4 results, which hold the audited full-year statements. For Japanese and Korean filers, quarterly covers Q1, half-year, and Q3 reports, and the Korean source forms are the DART codes 11011 to 11014. For metrics and facts, quarterly also returns every quarter-length value from other reports, including the fourth quarter, which is stored on the annual report. For commentary and risk_changes, annual covers 10-K and 20-F, quarterly covers 10-Q, and current covers 8-K. | |
| metric_class | No | Optional metric class for metrics or facts, such as financial, ifrs, segment, kpi, or apm. Matching ignores letter case, so Product and product select the same facts. | |
| fiscal_period | No | Optional company fiscal-period label, such as Q1, Q2, Q3, Q4, or FY. It applies to filings, metrics, and facts. For metrics and facts it selects the fiscal period a value covers; Q4 returns the fourth-quarter values stored on the annual report. | |
| search_target | No | Result type. coverage shows available report dates, types, and metric classes. filings shows report records and source URLs. metrics shows available concepts and series. facts shows numeric reported values. commentary shows management's qualitative statements from MD&A sections and earnings press releases. risk_changes shows year-over-year risk-factor changes from annual reports; no rows for a year means unchanged risk factors, not no risks. | facts |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations, disclosing that the search is deterministic and calls no language model, that json and pretty are never returned together, that active_only is force-enforced for non-admins, that an empty risk_changes period means unchanged risks rather than none, and that values may silently fall back to Twelve Data vendor data lacking filing/segment evidence. The one unresolved tension is that readOnlyHint=false implies possible state change, yet the text never explains any write or side effect; that gap keeps it at 4 rather than 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
This is an undifferentiated wall of roughly 800 words in a single block with no headings. Several rules are restated verbatim more than once (the MC vs MC.PA suffix example, possible_matches behavior, the country suffix list), and currency/jurisdiction detail is repeated across paragraphs. The length is partly earned by 14 parameters and six targets, but the redundancy and lack of structure mean not every sentence earns its place.
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, so return-shape explanation is not owed, and the description still covers the empty-result semantics, source citation convention, active_only enforcement, cross-jurisdiction report_type mapping, and vendor fallback behavior. Given the tool's complexity, an agent has everything needed to choose a target and interpret a result 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?
With 100% schema description coverage the baseline is 3, but the prose adds real semantics beyond the schema: concept vs query selection, FY returning Q4 full-year values, the country-specific meaning of report_type=quarterly/annual, Korean DART codes, and the "(reported line 2)" duplicate-series rule. It does repeat a fair amount already present in the schema descriptions (suffix rules, report_type examples), so it is additive but redundant in places.
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 opening states a specific verb and resource: "It searches structured facts and report metadata from one company's filed reports," then enumerates the exact coverage (SEC 10-K/10-Q/8-K/20-F/40-F/6-K plus German, UK, French, Swiss, Indian, Japanese and Korean issuer reports). This is unmistakably distinct from siblings like search_earnings_transcripts, search_news, or get_market_data. An agent knows exactly what resource it touches without opening the schema.
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 internal routing: "Use an exact ticker when possible," "Use query instead for a broad search across several concepts," and a full breakdown of when each search_target value applies. It also states coverage limits (commentary and risk_changes are SEC-only) and the vendor fallback condition. It stops short of naming sibling tools or stating explicit exclusions (e.g. when to prefer search_earnings_transcripts over commentary), so it is clear context without full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find datasets by keyword across every schema — the first discovery step.
Keyword ranking (not semantic) over dataset titles and topics. Returns ranked
{schema, dataset_code, title, topic}. Follow up with describe_dataset for
detail, or run_sql on the series/dimensions tables for exact series.
latest_data_date, when present, is the period start date of the newest
stored value in the whole dataset (left out when unknown); one part of a
dataset can stop earlier, so check the end dates of the series you use.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| schemas | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description supplies genuinely useful behavior beyond the annotations (keyword ranking rather than semantic, the returned fields, and the latest_data_date caveat), but it characterizes a pure read/search while the annotations declare readOnlyHint=false, idempotentHint=false and openWorldHint=false. That mismatch is a real inconsistency an agent could rely on incorrectly, so the transparency score is held down despite the otherwise rich detail.
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?
Front-loaded with purpose and scope, then ranking behavior, then alternatives, then a caveat 54 each sentence earns its place. The explicit list of returned fields is mildly redundant given an output schema exists, which keeps it from a 5.
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 discovery/search tool with an output schema and three simple parameters, the description covers purpose, ranking method, follow-up tools, and the latest_data_date interpretation caveat. Nothing an agent needs in order to call this 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 0%, so the description carries the burden. It explains the query parameter ('by keyword') and hints at the schemas parameter ('across every schema'), but the limit parameter and the exact semantics/allowed values of schemas are never described, so compensation is only partial.
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 gives a specific verb and resource ('Find datasets by keyword across every schema') and positions the tool in the workflow ('the first discovery step'), which immediately separates it from siblings like describe_dataset and run_sql. An agent can tell what this tool returns without opening the schema.
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 the agent onward: use describe_dataset for detail, or run_sql on the series/dimensions tables for exact series, and frames this tool as the first discovery step. The when-to-use condition is stated rather than inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search earnings-call intelligence from live calls, decomposed into atomic, quote-anchored claims and Q&A pressure points — never a raw transcript dump.
Retrieval for "claims" and "pressure_points" is lexical, not semantic. A nonempty query uses an OR-of-tokens full-text candidate set; strict websearch_to_tsquery matches receive a fixed ranking boost, so strict matches rank ahead of loose partial-term matches. Lower-ranked rows may match only some query terms. If that filtered full-text search returns no rows, a trigram fallback handles typos and sub-word variants. Quoted phrases use websearch syntax, but synonyms are not inferred: try the company's own vocabulary ("capex" and "capital expenditure", segment names, abbreviations). An empty or partial result is not proof that management did not discuss a topic; coverage and vocabulary both matter.
Target and filter semantics:
"claims" (default) searches or browses normalized management/analyst claim rows. ticker, quarter_filter, claim_family, section, detail, and limit apply. claim_family matches primary or secondary families; section is "prepared_remarks" or "qa". Base rows include direction/value/unit where checkable, assertion_status, canonical_statement, verbatim_quote, speaker, speaker_role, section, transcript_id, source_block_index, qa_turn_id, and a source_link object.
"pressure_points" searches or browses what analysts pressed for and whether management confirmed, declined, deflected, or partially answered. ticker, quarter_filter, claim_family (the linked family), detail, and limit apply. section is ignored because every pressure point is from Q&A. Base rows include specific_ask, response_quality, refused_number, linked_family, linked_claim_id, verbatim_quote, transcript_id, source_block_index, qa_turn_id, and a source_link object.
"disclosure_profile" is a direct company lookup, not text search. The ticker is the first ticker value, or query when ticker is empty. Profiles are curated separately from transcript coverage, so a covered company may not have one; availability is "available" or "unavailable" accordingly. quarter_filter, claim_family, section, detail, and limit do not narrow it.
"coverage" is corpus inventory, not text search. ticker and limit apply; query, quarter_filter, claim_family, section, and detail do not narrow it. Rows report calls_covered, earliest_period, latest_period, latest_call_date (the call date of latest_period), claims, and pressure_points.
An empty query is a capped browse, not a completeness guarantee. Rows are
ordered by newest fiscal period/call and then source-block (spoken) order
within one call. Every response is limited to at most 50 rows, and a browse
that reaches its limit may omit additional rows even if no truncation flag is
present. For a latest-call note: (1) call "coverage" with one ticker, (2) read
latest_period, (3) call "claims" with that ticker, quarter_filter=latest_period,
query="", detail=true, and a deliberate limit, then (4) call
"pressure_points" with the same ticker and quarter. Treat both browses as
capped evidence, not a complete transcript. Narrow large result sets with
ticker, quarter, target, claim_family, and (for claims) section. For media
quotes, run_sql can read transcripts.appearance_claims.verbatim_quote;
other transcript tables remain restricted.
Evidence rules: canonical_statement is normalized and must not be quoted as
verbatim. Quote only verbatim_quote, with its speaker, role, ticker, and fiscal
period. A […] inside verbatim_quote marks omitted transcript sentences between
non-adjacent evidence spans: preserve it exactly when quoting, and never
present text on either side of it as one continuous statement. When a quote is used, render source_link.source_label as the Markdown
link text for source_link.source_url beside the claim. The label names the
company, fiscal period, and earnings call transcript; never replace it with an
ingestion vendor. Do not make a second call just to find a citation, do not
invent a replacement when source_url is null, and do not call a document-level
link exact context. source_locator still identifies the stored transcript block
or Q&A turn. assertion_status is load-bearing: analyst_hypothesized is the
analyst's framing, while mgmt_declined_to_confirm is a refusal, not a management
assertion. Spoken call claims are a different source class from filed XBRL
actuals (run_sql on the sec schema) and formally issued targets (the
sec_guidance dataset); label them separately.
Examples:
Latest call: search_earnings_transcripts(query="", search_target="coverage", ticker="MU"), then repeat with search_target="claims", quarter_filter=<latest_period>, detail=true, limit=50, and finally with search_target="pressure_points" for the same ticker and quarter.
Cross-company theme: search_earnings_transcripts(query="capital expenditure capacity", search_target="claims", ticker="MU,NVDA", detail=true); inspect each returned row for topical support, do not assume every term matched, and retry vocabulary as needed.
Disclosure habits: search_earnings_transcripts(query="", search_target="disclosure_profile", ticker="MU").
claim_family codes: driver_attribution, forward_conviction, prior_view_revision, strategic_agreement, pricing_mechanics, demand_magnitude, capacity_milestone, competitive_positioning, cohort_behavior, cost_margin_bridge, capital_allocation, stated_risk_constraint, qa_dynamics, regulatory_policy, pipeline_backlog, commodity_hedging, ma_deal, labor_org. Topic paths (topic_path column) are rooted at: demand, supply_capacity, pricing, cost_margin, capital, competition, customer, product_roadmap, risk, governance.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum 1-50 rows (default 15). This is a hard cap, not proof the result is complete; narrow by ticker, quarter, target, family, and claims section. | |
| query | No | For claims/pressure_points: lexical websearch text; strict matches rank above loose partial-term matches, with trigram fallback only when FTS returns no rows. Empty text browses capped rows. For disclosure_profile, it can supply the ticker when ticker is empty. Ignored by coverage. | |
| detail | No | For claims, add structured_fields, secondary_families, period, time_horizon, conviction_qualifier, denominator, and falsifiable; for pressure_points, add tone_note. Ignored by disclosure_profile and coverage. The extractor's quantified flag is not published: it only records that the extractor wrote something into value, which the caller can already see in value itself. | |
| ticker | No | Ticker, or a comma-separated list of tickers, for claims, pressure_points, and coverage; case-insensitive. Company names belong in company_name; pass only one of the two. A name passed here is still read as a name when it fits a stored company, and the response says so. Companies listed in India carry the NSE suffix ('RELIANCE.NS', 'INFY.NS') and companies listed in Switzerland carry '.SW' ('NESN.SW', 'ROP.SW'); a plain NSE or Swiss symbol is also accepted, but a symbol that is a US ticker ('INFY', 'ROP') selects the US listing. The response lists possible matches for a value that is not in the transcript corpus. disclosure_profile uses only the first ticker. | |
| section | No | prepared_remarks or qa; applies only to claims. Ignored for pressure_points because those rows are all Q&A, and ignored by lookup/inventory targets. | |
| claim_family | No | Claim-family code. Matches primary/secondary families on claims and the linked family on pressure_points; ignored by disclosure_profile and coverage. | |
| company_name | No | Company name, or a comma-separated list of names, for claims, pressure_points, and coverage; case-insensitive ('nvidia', 'HP Inc', 'Ford Motor'). Each name resolves to the stored ticker(s) that match it best; the response reports the resolution and lists possible matches for a name that resolved to nothing. Pass either company_name or ticker, not both. disclosure_profile uses only the first resolved ticker. | |
| search_target | No | claims or pressure_points perform lexical retrieval/browse; disclosure_profile is a direct company lookup; coverage is corpus inventory. | claims |
| company_filter | No | Deprecated alias of ticker, kept for clients installed before the parameter was renamed. Pass ticker instead. | |
| quarter_filter | No | Exact fiscal period such as FY2026Q3; applies to claims and pressure_points. Ignored by disclosure_profile and coverage. Pin this after coverage for a single-call browse. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=false) disclose little operationally, but the description carries rich behavior: lexical-not-semantic retrieval, OR-of-tokens candidate sets, websearch_to_tsquery boost, trigram fallback, 50-row hard cap, newest-period/source-block ordering, and a full evidence/citation rulebook. This is substantially more than the annotations convey. (Minor tension: the description describes purely read-style retrieval while readOnlyHint=false, but it never asserts read-only-ness, so this is not a formal contradiction.)
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?
Front-loaded with purpose, then retrieval mechanics, target semantics, evidence rules, and examples — a sensible progressive structure for a genuinely complex 10-parameter, 4-target tool. It is dense and somewhat repetitive (the 50-row cap and 'capped browse' caveat are restated), but nearly every sentence carries operational weight.
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, so return fields need not be enumerated, yet the description still maps each target's base-row fields and the evidence/citation rules an agent needs to render results correctly. Given the tool's complexity, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all ten parameters; baseline is 3. The description adds value beyond the schema by enumerating the 19 `claim_family` codes and the root `topic_path` values (absent from the schema) and by giving a per-target applicability matrix (which of ticker/quarter_filter/claim_family/section/limit narrow each target).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Search earnings-call intelligence'), specifies the unit of retrieval ('atomic, quote-anchored claims and Q&A pressure points'), and explicitly distinguishes itself from a raw transcript dump and from the `run_sql`/`sec`/`sec_guidance` alternatives. An agent can identify the tool's scope without opening the schema.
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 explicit when-to-use routing across the four `search_target` modes, names sibling alternatives (`run_sql` for media quotes and XBRL actuals, the `sec_guidance` dataset for targets), gives a step-by-step latest-call recipe, and states exclusions ('do not make a second call just to find a citation'). Alternatives and negative conditions are both spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deterministically search precomputed intelligence from podcasts, TV interviews, and conference talks outside earnings calls, and from official documents published by central banks and monetary authorities (the Federal Reserve Board and regional Reserve Banks, the European Central Bank and euro-area national central banks, the Bank of England, the Bank of Japan, the Reserve Bank of India, the People's Bank of China, the Bank of Korea, the Hong Kong Monetary Authority, Taiwan's central bank, and others): speeches, testimony, policy statements, implementation notes, minutes, press-conference transcripts, projections, reports and press releases. Documents in other languages yield English paraphrases. The speakers are company executives, investors, fund managers, analysts, economists, journalists, central-bank officials, and other guests, and their claims cover listed and unlisted companies (OpenAI, DeepSeek, MiniMax), institutions (the Federal Reserve, the European Central Bank, regulators), and whole markets and industries, not only the speaker's own employer. No serving-time model interprets or expands the query.
Retrieval for structured findings is lexical, not semantic: strict full-text matching is tried first, loose any-term full-text matching only when strict matching returns no candidates, then trigram matching only when both full-text stages are empty. Natural-language questions work because person names and common question scaffolding are normalized. Prefer concise topical terms; retry synonyms or the speaker's own vocabulary before concluding there is no coverage.
Canonical search_target values:
"search" (default): blended structured claims and broad passage cards.
"claims": normalized decision-relevant claims only.
"passages": broad substantive paraphrase cards only.
"pressure_points": stored refusal and declined-to-confirm claim rows.
"appearances": video-level catalog rows.
"coverage": company-level structured-corpus inventory.
Compatibility aliases remain accepted for older clients: "all" maps to "search", "videos" to "appearances", and "companies" to "coverage". New callers should use the six canonical values; "search" is the primary blended target, not a legacy alias.
Result contracts:
search/claims/passages/pressure_points return result_kind, canonical_paraphrase, speaker, primary ticker, topic labels, video/channel/publication metadata, lexical relevance, and source_url (a timestamped YouTube deep link, the episode page for a podcast, the document page for an official document, or the PDF page of a press-conference transcript). detail=true adds normalized claim and attribution fields plus institution, document_kind and event_date (null for interviews), but never raw transcript text or evidence spans.
appearances returns video metadata, primary ticker, attribution metadata, matching claim count, URL, and relevance score. detail has no effect.
coverage returns company-level appearance, publication-date-span, channel, claim, and low-confidence-attribution counts. It is structured coverage, not a per-person acquired-video/hour inventory; query, sort, and detail have no effect.
Filter and ordering semantics:
company is comma-separated tickers and company names, mixed freely. A stored ticker matches the appearance's company or a section subject with that ticker; any other value is read as the name of a company, institution, or organisation a podcast section is about, matched after dropping punctuation, a leading "The", and corporate suffixes. Every ticker attached to a matched name joins the ticker filter, so "Alphabet" also reaches GOOGL rows. The result records company_tickers, company_names, company_matched, and company_unmatched (a value that matched nothing, with up to five possible matches); an unmatched value returns no rows, not an error. company_filter is the old name of company and behaves the same; passing both is an error. The appearances and coverage targets also match every value, upper-cased, against the entity references of claims (products, rivals, partners such as "CUDA"); a value found only there is listed under company_references. Alternate spellings can return different appearances or coverage rows because reference names are matched exactly ("open ai" and "OpenAI" select the same subject but not the same references); the claims rows are the same.
person is a case-insensitive substring over the finding speaker and/or appearance speaker metadata. appearance_type applies to every target: podcast, tv_interview, conference and other for interviews; speech, testimony, minutes, statement, press_conference and hearing for official documents. country ("US") restricts every target to official documents of that country; institution ("Federal Reserve") is described with show and channel below.
claim_family restricts structured claims. With blended search it suppresses passage cards; pairing it with search_target="passages" is an error. For appearances/coverage it requires videos with matching structured claims.
date_from/date_to are inclusive YYYY-MM-DD bounds on the video's stored publication/upload date, which can differ from the recording or event date.
show, channel, and institution are case-insensitive substrings of a podcast show name, a YouTube channel name, and a publishing institution; each returns only rows of its own kind, and when more than one is given rows matching any of them are returned.
relevance orders lexical score first, then publication date; newest orders publication date first, then lexical score. Coverage has fixed inventory ordering by latest covered publication date.
limit is one page of 1-50 rows and offset skips that many ranked rows before the page, so limit=15 with offset=15 returns rows 16-30 of the same ranking. Every result carries has_more, plus next_offset when more rows follow; call again with that offset to read the next page.
With an empty query, search and claims browse recent high-signal claims without generic passage cards; passages browses recent passage cards; pressure_points browses recent refusal rows; appearances browses the video catalog; coverage returns the company inventory. Each result set is capped at 1-50 rows.
Evidence safety: canonical_paraphrase is a normalized paraphrase, not a transcript quotation. Cite source_url (timestamped for YouTube, page-anchored for PDF transcripts) with the returned speaker, publication date, and video or document metadata. FOMC minutes describe the meeting of event_date and are published three weeks later; the Committee, not one person, is their speaker. Do not put canonical_paraphrase in quotation marks unless you independently verify the wording at the source link. The tool never returns raw transcript text.
Detail-field safety: detail adds normalized claim fields only. The extraction pipeline's internal audit flags are not published, because they describe how a row was built rather than anything checkable about the claim; judge a claim from value, assertion_status, and the timestamped source link instead. company_attribution_confidence and company_attribution_source concern only the video-to-company/ticker assignment; inferred attribution is not independent confirmation.
| Name | Required | Description | Default |
|---|---|---|---|
| show | No | Case-insensitive substring of a podcast show name, for example 'Odd Lots'. Returns podcast rows only. Combine with channel or institution to also include YouTube or official-document rows that match those; rows matching any given name filter are returned. | |
| sort | No | "relevance" orders lexical score first and publication date second; "newest" orders publication date first and lexical score second. Coverage uses its fixed company-inventory ordering. | relevance |
| limit | No | Maximum rows returned in one page, from 1 through 50. Use offset to read the pages after the first. | |
| query | No | Lexical search text. Natural-language questions are accepted because person/question scaffolding is normalized, not because a serving-time model interprets them. Use concise topical vocabulary and retry synonyms or the speaker's own terminology if needed. Ignored by coverage; appearances matches only video title/channel metadata. | |
| detail | No | For search/claims/passages/pressure_points, add normalized claim and company-attribution fields. Internal audit flags use bounded public names and include field_semantics; raw transcript text and evidence spans remain excluded. Has no effect on appearances or coverage rows. | |
| offset | No | Number of ranked rows to skip before the returned page, so offset=15 with limit=15 gives rows 16 through 30 of the same ranking. Every result reports has_more, and adds next_offset when more rows follow; repeat the call with that value to read the next page. | |
| person | No | Case-insensitive name substring matched against the result speaker and/or the appearance speaker metadata. | |
| channel | No | Case-insensitive substring of a YouTube channel name, for example 'Bloomberg Television'. Returns YouTube rows only. Combine with show or institution to also include podcast or official-document rows that match those; rows matching any given name filter are returned. | |
| company | No | Comma-separated tickers and company names, mixed freely (for example, 'NVDA,OpenAI' or 'Federal Reserve,Alphabet'). A value that is a stored ticker matches the appearance's company or a section subject with that ticker. Any other value is read as the name of a company, institution, or organisation the podcast section is about, so unlisted companies (OpenAI, MiniMax, Manycore Tech), central banks, and regulators are found by name. Names are matched after dropping punctuation, a leading 'The', and corporate suffixes ('NVIDIA Corp.' finds NVIDIA; 'Alphabet' also reaches GOOGL rows), and each result records how every value was read: company_tickers, company_names, company_matched, and company_unmatched (with up to five possible matches per value that matched nothing). The appearances and coverage targets also match every value, upper-cased, against the entity references of claims (products, rivals, partners such as 'CUDA' or 'ChatGPT'); a value found only there is listed under company_references. Alternate spellings can return different appearances or coverage rows because reference names are matched exactly ('open ai' and 'OpenAI' select the same subject but not the same references); the claims rows are the same. | |
| country | No | ISO country code of the institution that published an official document, for example 'US'. Restricts every target to official documents of that country. | |
| date_to | No | Inclusive YYYY-MM-DD upper bound on the video's stored publication/upload date, which may differ from its recording or event date. | |
| date_from | No | Inclusive YYYY-MM-DD lower bound on the video's stored publication/upload date, which may differ from its recording or event date. | |
| institution | No | Case-insensitive substring of the institution that published an official document, for example 'Federal Reserve'. Returns official-document rows only; podcast and YouTube rows have no institution. Combine with show or channel to also include podcast or YouTube rows that match those; rows matching any given name filter are returned. | |
| claim_family | No | Optional claim-ontology code. Blended search then returns structured claims only; appearances/coverage require matching claims. It is incompatible with search_target='passages'. Invalid codes return the valid vocabulary. | |
| search_target | No | Canonical targets: "search" (default blended claims + passages), "claims" (normalized decision-relevant claims), "passages" (broad substantive paraphrase cards), "pressure_points" (refusals and declined-to-confirm claims), "appearances" (video catalog), and "coverage" (company-level structured-corpus inventory). Compatibility aliases are "all" -> "search", "videos" -> "appearances", and "companies" -> "coverage"; new callers should use the canonical values. | search |
| company_filter | No | Old name of company. Accepted with the same behaviour; the response note asks the client to update its plugin. Do not pass both. | |
| appearance_type | No | Optional appearance-type filter. Interviews: podcast, tv_interview, conference, other. Official documents: speech, testimony, minutes, statement, press_conference, hearing. Applies to every canonical target. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations supplied, the description goes well beyond them: it discloses deterministic lexical (not semantic) retrieval with strict/loose/trigram fallback stages, per-target detail behavior, pagination via has_more/next_offset, and that raw transcript text and evidence spans are never returned. The only unexplained tension is with the annotations themselves — readOnlyHint=false and idempotentHint=false are never reconciled with an otherwise purely retrieval-shaped description, so the agent is left unsure whether the call has side effects.
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?
Section headers ('Result contracts', 'Filter and ordering semantics', 'Evidence safety', 'Detail-field safety') give it structure, and the purpose is front-loaded, but the whole is roughly 700 words with heavy duplication of parameter descriptions already present in the schema. Much of that space does not earn its place in a description that sits alongside a fully documented 17-parameter schema.
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 17-parameter, multi-target search tool with an output schema, the definition covers everything an agent needs: target semantics, filter resolution and error cases, paging, empty-query behavior, and citation/evidence-safety caveats ('canonical_paraphrase' is a paraphrase, FOMC minutes' speaker is the Committee, attribution confidence is not independent confirmation). No material calling gap remains.
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, but the description adds system-level semantics the schema only hints at: company vs company_filter being mutually exclusive, claim_family suppressing passage cards and erroring with search_target='passages', detail having no effect on appearances/coverage, and coverage ignoring query/sort/detail. A large portion of the company-filter prose, however, duplicates the schema description nearly verbatim, so the added value is real but partial.
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 opening states a specific verb and resource (searching precomputed intelligence from podcasts, TV interviews, conference talks, and central-bank/official documents) and explicitly carves out the scope it does *not* cover ('outside earnings calls'), which distinguishes it from the sibling search_earnings_transcripts. An agent can identify the corpus and the target domain without opening the schema.
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 unusually rich in-tool guidance: how to pick among the six canonical search_target values, to prefer concise topical terms and retry synonyms or the speaker's own vocabulary, what each target does on an empty query, and which parameter combinations are errors (claim_family with passages, company with company_filter). It never explicitly names a sibling tool or says 'use search_company_filings instead', so routing across the toolset is only implied by the 'outside earnings calls' carve-out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search recent business, economics and health news from major financial
publishers and public-health agencies. Each row has the headline, the
publisher's short summary and a link (article bodies are never returned), plus
FactIQ metadata: tickers of listed companies named in the text and an
analysis block (keywords, geography, and a one-sentence investor angle).
Coverage starts between late 2024 and mid 2026, depending on the feed. All
arguments combine (AND).
query: lexical full-text search over headline, summary and analysis; every word must match. Start with ONE distinctive term ("Novartis", "copper"). If nothing matches, it retries matching ANY word (meta.query_mode = "any_term"). Supports "exact phrases" and -exclusion.
tickers: bare symbols (["NVDA", "RELIANCE"]). Share classes and cross-listings match automatically (GOOG = GOOGL, TSM = 2330).
topic: one of markets, economics, companies, technology, politics, world, energy, health, india, opinion. With a query it only boosts that topic's articles; without one it filters to them.
start_date / end_date: inclusive ISO dates on publication time.
sources: publisher slugs, as shown in the source field of results.
sort: "latest" (default) or "relevance" (needs a query).
limit: 1-50, default 20.
Returns {rows: [{id, published_at, source, feed, topics, title, summary, url,
tickers, analysis}], meta: {matched, returned, sort, query_mode?,
topic_mode?}}. analysis is null when an article has no business content
or is not yet analysed. Follow up macro stories with search_series / run_sql
and company stories with get_market_data / search_earnings_transcripts.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | latest | |
| limit | No | ||
| query | No | ||
| topic | No | ||
| sources | No | ||
| tickers | No | ||
| end_date | No | ||
| start_date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (openWorldHint=true, destructiveHint=false) cover the safety profile, yet the description adds real behavioral context: article bodies are never returned, coverage windows vary by feed, a failed query silently retries with query_mode='any_term', and analysis is null for non-business or unanalysed articles. It omits any note on rate limits or auth, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well front-loaded (purpose, then output shape, then coverage caveats, then per-parameter bullets) and the bulleted layout is easy to scan, with every sentence carrying information. It is long, and the 'Returns {...}' block partly restates the existing output schema, so it is not maximally tight.
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 an 8-parameter tool with 0% schema coverage, the description is complete: all arguments are documented, result shape and null semantics are noted, the retry fallback is disclosed, and follow-up tools are named. Nothing an agent needs to invoke it correctly is missing, and the return detail is bonus given an output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden and does: it documents every one of the 8 parameters with semantics the schema lacks (lexical AND semantics, phrase/-exclusion syntax, cross-listing ticker matching, the 10 topic values and their boost-vs-filter behavior, inclusive ISO dates, publisher slugs sourced from results, sort='relevance' requiring a query, limit bounds).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource+'recent business, economics and health news from major financial publishers and public-health agencies', which tells an agent exactly what corpus it searches. The closing routing sentence names sibling tools (search_series, run_sql, get_market_data, search_earnings_transcripts), cleanly separating it from adjacent 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?
Gives explicit when-to-use and what-to-do-next guidance: 'Follow up macro stories with search_series / run_sql and company stories with get_market_data / search_earnings_transcripts.' It also prescribes search strategy ('Start with ONE distinctive term'), states that arguments AND together, and explains that topic boosts with a query but filters without one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find series in one schema by title terms (substring match, not semantic).
Supply already-decomposed terms; prefer short stems (e.g. "rare" over "rare
earth"). Includes active COMPOUND:: series. For anything this misses, fall
back to run_sql exploration on the series and dimensions tables.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| terms | Yes | ||
| schema | Yes | ||
| include_compound | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds genuinely useful behavior beyond the annotations: the match is substring, not semantic, COMPOUND:: series are included, and coverage has a known fallback path. Annotations are thin and partly odd (readOnlyHint=false on an obviously read-oriented search), but the description never explicitly claims read-only, so this is a gap rather than a contradiction.
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 tight sentences, front-loaded with purpose and matching semantics, then query-shaping advice, then the fallback. Every clause earns its place with 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?
An output schema exists so return values need no explanation, and the description covers scope, matching mode, and the escape hatch when results are missin. It leaves `limit`/pagination behavior and term-combination semantics unexplained, which is the remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry all four parameters. It explains `terms` well (decomposed, short stems) and implies `schema` ("in one schema") and `include_compound` ("Includes active COMPOUND:: series"), but says nothing about `limit` or how term arrays are combined (AND vs OR). Partial compensation for a 0% coverage schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (find series in one schema by title terms) and immediately pins down the matching mechanism as substring rather than semantic. It also names what the tool does not cover and routes to the run_sql sibling, so an agent can distinguish it from get_series and run_sql 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit guidance on when to use it (substring title search), how to shape the query (already-decomposed terms, short stems), and where to go when it fails (run_sql over series/dimensions tables). That is when-to-use, how-to-use, and a named alternative in three sentences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report a problem with FactIQ's data or tools to the FactIQ team.
Call this when a tool result looks broken:
"data_issue" — a value that contradicts the official source, wrong units or scale, duplicated or missing periods, an obviously wrong label.
"tool_error" — a tool that errors, times out repeatedly, or returns malformed or self-contradictory results.
"missing_data" — a dataset or series the catalog advertises but that returns nothing, or coverage that ends far earlier than the source's.
"other" — a concrete defect in the published tool contract, such as the documented arguments or result shape contradicting actual behavior.
Write one short, specific message with the concrete identifiers: the schema, dataset_code or series_id, the SQL you ran, and what you expected vs. what you got (with the official source's value or URL if you have one). Do not include the user's personal details or your conversation.
Do not call this for intentional capability boundaries or simply because a user requested an unsupported action. FactIQ cannot mutate warehouse data, return complete raw transcripts, or publicly publish charts/reports; those limits are expected behavior, not defects. A concrete tool result must show the reported malfunction or data problem.
This is one-way: the FactIQ team reviews every report, but nothing comes back to you. File it and continue with the user's task — never block on it.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | ||
| category | No | other |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-readOnly, non-idempotent, openWorld, destructive; the description adds meaningful context beyond them: the report is one-way, the team reviews it, and the agent must not block on it. It also warns against including personal details. Minor remaining gaps (rate limits, dedup of repeat reports) are not covered.
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?
Front-loaded with the purpose, then organized into scannable bullets for categories, message guidance, exclusions, and one-way behavior. Length is justified by the number of distinct rules and no sentence is wasted.
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 so return values need no explanation, and the description nonetheless clarifies the one-way (no-response) nature. Combined with category semantics and content required for the message, an agent has everything needed to file a well-formed report.
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 0% and the schema carries no descriptions, so the description must compensate — and it does, defining each enum value of 'category' with examples and specifying what the 'message' should contain (identifiers, SQL run, expected vs. actual). Only the 4000-char bound goes unmentioned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the specific verb+resource ('Report a problem with FactIQ's data or tools to the FactIQ team') and pins the scope precisely to broken tool results. An agent can immediately distinguish it from all data-retrieval 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?
Explicitly enumerates when to call it (four defect categories with concrete examples) and, more valuably, when NOT to call it (intentional capability boundaries, user-requested unsupported actions). It also states the non-blocking behavior, so the agent knows how to sequence this relative to the user's task.
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.
describe_datasetget_data_catalogget_geo_dataget_market_dataget_seriesget_style_guidesrun_sqlsearch_company_filingssearch_datasetssearch_earnings_transcriptssearch_media_appearancessearch_newssearch_seriessend_feedback
Add one secure layer between your agents and this server.