Grounded financial research for agents: filings, transcripts, news across US and Asia markets.
Scored across 10 tools
Tools mostly have clearly distinct purposes: catalog/schema discovery, row queries, aggregates, async qualitative screens, library search/fetch, and job polling. However, screen_drivers and screen_earnings share the same async job pattern and could be confused, and query_entity and aggregate_entity overlap on entity reads though descriptions steer usage. These minor overlaps keep it from a perfect score.
The set uses a consistent snake_case verb_noun pattern for almost all tools: list_queryable_entities, describe_queryable_entities, query_entity, aggregate_entity, get_library_document, get_screen_job, screen_drivers, screen_earnings, search_public_library. The only outlier is ping, which is a minor deviation but still readable.
With 10 tools, the set is well-scoped for a financial data read/search/screen surface. Each tool has a clear role, and there is no obvious excess or missing basic operation at the count level.
The surface covers catalog discovery, schema description, row queries, aggregates, qualitative screens, job polling, and public library search/fetch. Minor gaps exist, such as no explicit screen job listing/cancel and no dedicated raw filing text retrieval, but agents can work around these within the stated scope.
Read one Queryable Entity as a GROUP BY aggregate. Returns one page of groups. Use this for a count, a per-group min/max/avg, or a threshold screen. Do not page raw rows through query_entity for those. Call list_queryable_entities first, then describe_queryable_entities.
Use cases:
Count rows or companies that match filters: COUNT on id, with the same filters as a row query.
Range over time: MIN and MAX of a metric, group_by company_id. Example: forward P/E on valuation_multiple, filter type and valuation_date, alias the outputs minPe and maxPe.
Threshold screen: MAX(value) as an alias, category and date filters in filters, numeric cut in having on that alias. The number of returned groups is the match count. Then query_entity on company with id in [...] to attach names, tickers, and hq_country.
Allowed entities: company, company_drivers, consensus_data_point, consensus_metric, earnings_calendar, executive_summary, file, financial_data_point, financial_metric, knowledge_unit, ku_cell, price_explanation, product, product_category, sector, standard_event, stock_price, ticker, time_period, valuation_multiple.
Arguments: entity, aggregates, group_by, filters, filter_logic (AND or OR, default AND), having, sort, joins, limit. Each aggregate has function, field, optional alias, and optional distinct. Functions: COUNT, SUM, AVG, MIN, MAX. AVG is the arithmetic mean, not a median or percentile. filters are WHERE. having is HAVING and may use aggregate aliases. sort may use those aliases. Joins and camelCase aliases work like query_entity. Pass IN lists on filter.value. Do not pass value_path.
valuation_multiple.value, financial_data_point.value, and consensus_data_point.value are text. MIN, MAX, SUM, and AVG cast them to numeric and skip rows that are not decimals. A WHERE filter on those fields stays lexicographic. Put the numeric threshold in having, not in filters.
On financial_data_point, join time_period (alias timePeriod) and financial_metric (alias financialMetric). Group by timePeriod.company_id. Do not join company. Put metric name, provenance, duration, and fiscal_year in filters.
A full page sets truncated=true. This call does not scan the full universe. There is no next_hint. If truncated, tighten filters, drop a group_by column, or split an id list into smaller IN batches that each stay under max_limit. limit above max_limit fails.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | ||
| joins | No | ||
| limit | No | ||
| entity | Yes | ||
| having | No | ||
| filters | No | ||
| group_by | No | ||
| aggregates | Yes | ||
| filter_logic | No | AND |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial non-obvious behavior: truncation signaled by truncated=true, no next_hint, tighter-filter and batch-splitting remedies, limit above max_limit failing, and the cast-vs-lexicographic semantics of text value fields. This is exactly the extra context annotations cannot express.
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 use cases, and every section is relevant. It is dense and long, and a few clauses (e.g., the valuation_multiple example detail) could be trimmed, but for a 9-parameter tool with zero schema documentation the length is largely justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still explains the return contract (one page of groups, one group per match via HAVING, truncated flag) and the paging failure mode. Combined with allowed-entity and join guidance, an agent has everything needed to call this 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%, so the description must carry the load and it does: it enumerates every argument, defines the aggregate function set and alias/distinct sub-fields, explains filter_logic default, distinguishes filters (WHERE) from having (HAVING, may use aliases), and notes joins/camelCase alias behavior plus the 'no value_path' constraint.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource ('Read one Queryable Entity as a GROUP BY aggregate') and immediately scopes the return shape ('Returns one page of groups'). It explicitly distinguishes itself from the sibling query_entity ('Do not page raw rows through query_entity for those'), so an agent can route between them without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Three concrete use cases (count, per-group min/max/avg, threshold screen) with worked examples, plus an explicit exclusion of the wrong alternative. It also gives the required workflow ordering: call list_queryable_entities first, then describe_queryable_entities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe the schema of one or more Queryable Entities. Call list_queryable_entities first. Call this before query_entity and aggregate_entity. Pass one comma-separated list of the base entity and every join target you will use (for example financial_data_point,time_period,financial_metric). Prefer suggested_describe_entities from the catalog. Returns field names, types, descriptions, operators, select/filter/sort flags, join_target, join_relation when it differs from join_target, max_limit, and notes. An unknown name returns known_entities. Use only fields and operators from this response.
| Name | Required | Description | Default |
|---|---|---|---|
| entity | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuine behavior beyond them: unknown names return known_entities (error path), the exact contents of the response, and the constraint that only returned fields and operators may be used. It does not discuss rate limits or caching, so 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?
Short imperative sentences, front-loaded with purpose then workflow then parameter format then return contents. Every clause carries information an agent must act on; 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?
No output schema exists, so the description enumerates the response shape (fields, types, operators, flags, join_target, join_relation, max_limit, notes) and the error behavior. Nothing needed 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 coverage is 0% and the single parameter is misleadingly named 'entity', but the description disambiguates it fully: one comma-separated list of the base entity plus every join target, with a concrete example. That is strong compensation for an otherwise undocumented parameter.
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 ('Describe the schema of one or more Queryable Entities') and positions itself against siblings by naming list_queryable_entities, query_entity and aggregate_entity. An agent can place it in the workflow without opening any 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 ordering rules: call list_queryable_entities first, call this before query_entity and aggregate_entity, and prefer suggested_describe_entities from the catalog. Both the when and the preferred source of the argument are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one Public Library document by document_id from search_public_library sources. Returns metadata, summary, and tags. Pass with_contents=true to include raw text in contents for non-Research documents. Research documents omit full text (provider terms) and set contents_omitted. Omit with_contents to keep the payload small. This tool does not search. Call search_public_library first.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | ||
| with_contents | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds behavior beyond that: it discloses the return shape (metadata, summary, tags), the contents_omitted side effect for Research documents due to provider terms, and payload-size tradeoffs. Strong added value; only lacks pagination/error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four compact sentences, front-loaded with the core action, then return shape, then the parameter rule, then the sibling routing. No filler; 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?
For a 2-param read-only tool with no output schema, the description covers purpose, sibling routing, return shape, conditional parameter behavior, and the Research-document omission exception. An agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry parameter meaning. It does: document_id is the lookup key, and with_contents=true is documented with its effect ('include raw text in contents for non-Research documents') plus the default-off rationale. Only short of 5 because format/examples for document_id are not given.
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 ('Read one Public Library document by document_id') and explicitly distinguishes itself from its sibling: 'This tool does not search. Call search_public_library first.' An agent can tell it apart from search_public_library without inspecting schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this vs the alternative ('does not search. Call search_public_library first') and provides a conditional payload rule ('Omit with_contents to keep the payload small'). Routing and prerequisites are both covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one screen job that you started with screen_drivers or screen_earnings. Pass the job_id from the start call. This tool only reads GCS; it does not run the screen. Poll until status is "done" or "error". When status is "done", the payload includes result with the same JSON shape as a finished screen: summary, matches, ranked, and coverage. When status is queued or running, result is absent. When status is error, the payload includes error.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description goes well beyond that by disclosing the full job state machine (queued, running, done, error) and which payload fields appear in each state. This is exactly the polling and cardinality behavior an agent needs and structured fields do not carry.
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?
Six short sentences, front-loaded with what the tool is and where the job_id comes from, then progressively narrower detail about polling and per-status payloads. No filler and nothing repeated from the schema or annotations.
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?
There is no output schema, so the description carries the return-value burden and does so: result appears only on 'done' with summary/matches/ranked/coverage, is absent while queued or running, and an error field appears on failure. An agent can poll correctly and interpret every response without further documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and there is a single required parameter, but the description supplies the one thing the schema omits: the provenance of job_id ('from the start call'). It adds real meaning over a bare 'Job Id' string field, though no format or length guidance is given.
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 ('Read one screen job') and immediately ties it to the sibling tools that produce the job (screen_drivers, screen_earnings), which no other sibling does. An agent can distinguish this from its siblings without opening any 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 usage context: pass the job_id returned by the start call, and poll until status is 'done' or 'error'. It also states the negative case — 'This tool only reads GCS; it does not run the screen' — routing agents to screen_drivers/screen_earnings when they actually want to launch work.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Queryable Entities this MCP may read. Call this before describe_queryable_entities, query_entity, and aggregate_entity. The catalog is the source of truth: names, descriptions, aliases, one-hop join_targets, and suggested_describe_entities. Pass suggested_describe_entities into one describe_queryable_entities call. Coverage is the public catalog: companies, prices, fundamentals, valuation, consensus, events, filings, and filings-derived knowledge-unit cells. There is no private watchlist, portfolio, or user profile.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantive context beyond them: the fields the catalog exposes, the exact coverage scope (companies, prices, filings, etc.), and a clear exclusion statement ('no private watchlist, portfolio, or user profile') that prevents futile calls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose and the workflow call-to-action, then the catalog contents and scope. Dense but each sentence carries information; the coverage sentence is long but earns its place by bounding expectations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no parameters, the description fully carries the burden: it enumerates the returned fields, defines coverage scope, states exclusions, and gives ordering guidance relative to siblings. Nothing needed 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?
Zero parameters and 100% schema coverage, so the parameter dimension is trivially satisfied. No parameter meaning needs explaining; the description correctly spends no space on inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('List Queryable Entities this MCP may read') and characterizes what the catalog contains (names, descriptions, aliases, join_targets). It also differentiates itself from siblings by naming describe_queryable_entities, query_entity, and aggregate_entity as downstream steps.
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 prescribes when to call it: 'Call this before describe_queryable_entities, query_entity, and aggregate_entity,' and tells the agent to feed suggested_describe_entities into a single describe call. This is explicit workflow guidance, not implied usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return pong plus the input message.
| Name | Required | Description | Default |
|---|---|---|---|
| message | No | hello |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds only that the response includes 'pong' plus the input message, which is marginal extra context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence, front-loaded with the action and the return value, with zero wasted words.
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 trivial echo tool with full annotation coverage and an existing output schema, the single sentence is close to sufficient. The only missing piece is any note about its intended use (liveness/connectivity checking).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies that the single 'message' parameter is echoed back in the response, which is meaningful, but does not describe format, length, or default behavior.
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 action (return pong plus the input message), making the echo/health-check nature instantly clear. It doesn't need sibling differentiation since none of the listed query/library tools do anything similar, but it also never says why it exists.
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?
No indication of when to use this tool, when not to, or what alternatives exist. An agent must infer it's a connectivity/liveness check with no supporting guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one page of rows from one Queryable Entity. Use this for a point lookup, a multi-period history, or a filtered list. Call list_queryable_entities first, then describe_queryable_entities.
What you can read:
company: name, ticker, sector, HQ country. Screen tools need these integer ids.
stock_price: daily prices, volume, dividends, and splits. price_explanation: why a significant price move happened.
financial_data_point: one row per statement line or ratio per fiscal period. Join time_period and financial_metric. Discover metric keys on financial_metric (name like '%net_debt%' finds pre-computed ratios).
valuation_multiple: multiples such as P/E and EV/EBITDA, by company and date.
consensus_data_point: analyst estimates. Join time_period and consensus_metric. The fiscal period is on time_period (fiscal_year, fiscal_quarter, end_date). consensus_date is the estimate snapshot date, not the fiscal period.
earnings_calendar: earnings dates. standard_event: corporate events; for earnings, filter type to "Earnings announcement". file: filings, transcripts, and news. Join company and filter company.symbol.
ku_cell: filings-derived knowledge-unit cells. Filter ku.name. An unfiltered read is a short slice of ids. knowledge_unit holds the definitions. company_drivers and executive_summary are per-company narratives. For a qualitative screen across many companies, use screen_drivers or screen_earnings.
sector, product, product_category (companies that share a category are peers), and ticker: catalogs. List sector in full. Do not resolve a sector with a single-word like filter.
Allowed entities: company, company_drivers, consensus_data_point, consensus_metric, earnings_calendar, executive_summary, file, financial_data_point, financial_metric, knowledge_unit, ku_cell, price_explanation, product, product_category, sector, standard_event, stock_price, ticker, time_period, valuation_multiple.
Arguments: entity, select, filters, filter_logic (AND or OR, default AND), sort, joins, limit. Filter operators: =, !=, >, >=, <, <=, in, like. Pass IN lists on filter.value. Do not pass value_path.
Joins: when a field has join_target, join that table and use alias.field in select, filters, and sort. Many tickers in one query: company.symbol in ["AAPL","MSFT"]. Use a camelCase alias (timePeriod, financialMetric). joins.relation is join_relation when describe shows it, otherwise join_target. On ku_cell, describe knowledge_unit but join relation ku. Other ku_cell relations: groupCompany, cellTimePeriod, cellStandardEvent, groupProductCategory, cellProductCategory. The name product_category matches two ku_cell relations, so it is rejected.
financial_data_point accepts only time_period and financial_metric joins. Do not join company. Filter timePeriod.company_id. Reported actuals use timePeriod.provenance = financials and timePeriod.duration = year. This table has no geographic revenue, segment mix, customer geography, or tariff exposure.
valuation_multiple.value, financial_data_point.value, and consensus_data_point.value are stored as text. A filter on them compares lexicographically ("100" < "99"). For a numeric threshold, use aggregate_entity and put the cut in having.
company.hq_country stores codes and full names. Filter both, for example in ["JP","Japan"]. HK is Hong Kong. CN is mainland China. They do not overlap. Other codes: US, KR.
limit above the entity max_limit (from describe) fails. A full page sets truncated=true and may include next_hint {field:"id", op:">", value:}. Add that filter, sort by id asc, include id in select, and repeat. There is no offset. For COUNT, SUM, AVG, MIN, MAX, or a threshold screen, use aggregate_entity.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | ||
| joins | No | ||
| limit | No | ||
| entity | Yes | ||
| select | No | ||
| filters | No | ||
| filter_logic | No | AND |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds substantial behavioral detail beyond those annotations: limit above entity max_limit fails, a full page sets truncated=true and may include next_hint, there is no offset, and pagination must be driven by id > last id with id in select and sort by id asc. It also warns that valuation_multiple.value, financial_data_point.value, and consensus_data_point.value are stored as text and filter lexicographically, and that financial_data_point accepts only time_period and financial_metric joins.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but the complexity of the tool and the 0% schema description coverage justify most of the length. It is front-loaded with purpose and usage, then structured into readable sections for entities, arguments, joins, and edge cases. The only minor cost is that it remains dense and includes some repetition, such as listing allowed entities after already describing them individually.
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 query tool with no output schema and no schema parameter descriptions, the definition is remarkably complete. It covers purpose, usage routing, entity semantics, argument construction, join rules, pagination behavior, special text-storage comparison behavior, and explicit tool alternatives for aggregation and screening. An agent can call it correctly without needing to infer major behavior from external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage across 7 parameters, so the description must carry the parameter burden. It documents entity, select, filters, filter_logic (AND or OR, default AND), sort, joins, and limit, including allowed filter operators, IN lists on filter.value, and the prohibition on value_path. It also explains join semantics, alias usage, and special join relation handling for ku_cell and financial_data_point.
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: "Read one page of rows from one Queryable Entity." It immediately distinguishes three use cases (point lookup, multi-period history, filtered list) and routes the agent to list_queryable_entities and describe_queryable_entities before calling. It also names aggregate_entity, screen_drivers, and screen_earnings for adjacent cases, so sibling differentiation is explicit.
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 direct when-to-use guidance and prerequisites: call list_queryable_entities first, then describe_queryable_entities. It explicitly says to use aggregate_entity for COUNT, SUM, AVG, MIN, MAX, or threshold screens, and to use screen_drivers or screen_earnings for qualitative screens across many companies. That covers when this tool is appropriate and when alternatives are better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Screen each company's fundamental drivers profile against a qualitative criterion such as "depends on AI hyperscaler capex as a primary growth driver", "sensitive to long-end interest rates via mortgage origination", or "tied to Chinese consumer recovery via outbound tourism". Backed by company_drivers — one synthesized profile per company (Type / Topic / Causal Relationship / Support / Current vs. Past). This is durable thesis-level structure, not a recent event.
Pass exactly ONE of:
company_ids: explicit DB integer IDs (obtain via query_entity on company).
universe: region scopes from all, us, cn, jp, hk, kr. Use ["all"] to scan every company; combine codes (e.g. ["us", "jp"]) to scan those HQ regions. If both are set, company_ids wins and universe is ignored.
No per-call upper bound on N. Large universes including universe=["all"] run in 100-company chunks. No lookback_days — drivers are continuously updated, one row per company.
This tool starts a screen job and returns at once. It does not run the screen in this request. The first response is { "job_id": "...", "status": "queued" }. Then call get_screen_job(job_id) until status is "done" or "error". When status is "done", get_screen_job returns result with summary, matches (the top_n rows), ranked (the full ranked list), and coverage counts. There is no VFS path.
Use this tool for what drives a company over time. Do not use it for a discrete dated event, earnings-period commentary, or a price move attributed to a driver. For exact field filters on company_drivers, use query_entity.
Do not split one thematic question into parallel sector-narrowed calls. Issue one call at the full universe scope, raise top_n if you need more breadth, and group sectors from ranked.
| Name | Required | Description | Default |
|---|---|---|---|
| top_n | No | ||
| criteria | Yes | ||
| universe | No | ||
| score_all | No | ||
| company_ids | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavior far beyond the annotations: the tool is asynchronous (returns {job_id, status:'queued'} immediately and does not run the screen), must be polled via get_screen_job until 'done'/'error', large universes run in 100-company chunks, there is no per-call N bound, no lookback_days, and no VFS path. This is exactly the operational context an agent needs and that annotations (readOnlyHint=false, idempotentHint=false) cannot supply.
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 the purpose and then uses bulleted, scannable blocks for the parameter rules and the job workflow; nearly every sentence is functional. It is on the long side and a few clauses (e.g. the driver profile parenthetical) could be tightened, but there is no true filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an async job tool with no output schema and thin annotations, the description supplies the full picture: return shapes at each stage, what the eventual result contains (summary, matches, ranked, coverage counts), and the polling contract. An agent can drive the tool end-to-end without further inference.
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 0% schema coverage the description must carry the burden, and it does for four of five params: it defines company_ids, universe (with valid region codes and combination semantics), the mutual-exclusion precedence rule, and top_n's role in controlling breadth. The fifth parameter, score_all, is never mentioned, leaving a genuine 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 (screen) and resource (company's fundamental drivers profile) against a qualitative criterion, with three concrete example criteria that make the abstraction tangible. It explicitly distinguishes itself from siblings by naming query_entity for exact field filters and by excluding event/earnings use cases that map to screen_earnings.
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 ('what drives a company over time') and when-not ('discrete dated event, earnings-period commentary, or a price move attributed to a driver'), plus alternatives (query_entity). It also spells out call-shape rules: pass exactly one of company_ids vs. universe, company_ids wins on conflict, and do not split one thematic question into parallel sector-narrowed calls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Screen each company's earnings-document cells (10-K, 10-Q, 8-K, 20-F, 6-K, earnings-call transcripts, and related filings extracted into the Earnings Database) against a qualitative criterion such as "explicitly mentioned tariff exposure as a near-term margin headwind" or "called out AI-driven cost savings as a guidance lever". Backed by ku_cell — LLM-extracted structured content from each company's most recent composite earnings filings per fiscal reporting period.
Pass exactly ONE of:
company_ids: explicit DB integer IDs (obtain via query_entity on company).
universe: region scopes from all, us, cn, jp, hk, kr. Use ["all"] to scan every company; combine codes (e.g. ["us", "jp"]) to scan those HQ regions. If both are set, company_ids wins and universe is ignored.
No per-call upper bound on N. Large universes including universe=["all"] run in 100-company chunks. periods is the number of recent reporting periods per company (default 4).
This tool starts a screen job and returns at once. It does not run the screen in this request. The first response is { "job_id": "...", "status": "queued" }. Then call get_screen_job(job_id) until status is "done" or "error". When status is "done", get_screen_job returns result with summary, matches (the top_n rows), ranked (the full ranked list), and coverage counts. There is no VFS path.
Use this tool for qualitative earnings-period commentary. Do not use it for durable thesis-level drivers (use screen_drivers) or for exact field filters on ku_cell (use query_entity).
Do not split one thematic question into parallel sector-narrowed calls. Issue one call at the full universe scope, raise top_n if you need more breadth, and group sectors from ranked.
| Name | Required | Description | Default |
|---|---|---|---|
| top_n | No | ||
| periods | No | ||
| criteria | Yes | ||
| universe | No | ||
| company_ids | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnly=false/idempotent=false/destructive=false; the description adds the genuinely non-obvious behavior: this is asynchronous, it queues and returns {job_id, status:'queued'} at once, requires polling get_screen_job until done/error, runs in 100-company chunks for large universes, and has no VFS path. This is behavior the agent could not infer from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Long but front-loaded and organized into purpose, parameter routing, and lifecycle sections; every block adds operational value. Slightly dense in the criteria examples, but no dead sentences.
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?
Despite no output schema, the description explains the two-phase response contract and what get_screen_job returns on completion (summary, matches/top_n rows, ranked, coverage counts). Combined with the parameter rules and async lifecycle, an agent has everything needed to invoke and follow through.
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%, so the description must carry parameter meaning and it does: company_ids vs universe with precedence rule ('company_ids wins and universe is ignored'), the universe code vocabulary (all/us/cn/jp/hk/kr) with combination semantics, periods as recent reporting periods per company (default 4), and top_n via 'raise top_n if you need more breadth'.
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 (screen) and resource (earnings-document cells across 10-K/10-Q/8-K/transcripts), names the backing dataset (ku_cell), and gives two concrete example criteria. An agent can immediately distinguish this from screen_drivers (durable drivers) and query_entity (exact field filters), both named 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?
Explicitly covers when to use ('qualitative earnings-period commentary'), when not ('durable thesis-level drivers' → screen_drivers; 'exact field filters on ku_cell' → query_entity), and even an anti-pattern ('do not split one thematic question into parallel sector-narrowed calls; issue one call at full universe scope').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the Public Library. The corpus is the public library, not the caller's private uploads. This is the same Agent2 public-library search: an LLM scope planner plus semantic retrieval. query is required and is a natural-language question or topic (for example "Acquired NVDA episode" or "tariff exposure"). Optional doc_types restrict Type tags: "Research", "Podcast". Optional tickers scopes to Company tags. Optional date_range is one lookback bucket: 7d, 30d, 60d, 90d, 180d, 200d, 1y. Optional brokers hard-filters by research firm. sole_company=true keeps only single-Company-tag docs and needs exactly one ticker. mode is synthesize (default) or list. synthesize returns a narrative answer from semantic passages (a sample, not an exhaustive sweep). list returns a catalog of matching documents. Unknown mode values become synthesize, as in Agent2. The JSON has mode, answer, and sources. Each source has document_id plus title, type, and publication_date when present. This tool does not return full document text. Call get_library_document with one document_id for tags or raw text. Research documents never include full text.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| query | Yes | ||
| brokers | No | ||
| tickers | No | ||
| doc_types | No | ||
| date_range | No | ||
| sole_company | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, it discloses non-obvious behavior: synthesize returns 'a sample, not an exhaustive sweep', unknown mode values silently become synthesize, and research documents never include full text. These are exactly the traits annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and corpus scoping are front-loaded, then parameters, then return shape — well ordered and dense. Minor waste in the two references to 'Agent2' ('the same Agent2 public-library search', 'as in Agent2') which add little for a caller.
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 search tool with no output schema, the description documents the full return shape (mode, answer, sources with document_id/title/type/publication_date) and the full-text limitation. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage the description carries the full burden and does: query is natural-language, doc_types restricted to 'Research'/'Podcast', date_range as discrete buckets (7d–1y), brokers as firm filter, sole_company requiring exactly one ticker, and mode's default plus fallback. This fully compensates for the empty schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Search the Public Library') and immediately scopes the corpus ('the public library, not the caller's private uploads'), which is the key disambiguator. An agent can tell this apart from private-upload or entity-query siblings 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?
Clearly frames the search context (semantic retrieval over the public library; query required, natural-language question/topic) and routes the agent to get_library_document for full text/tags. It stops short of explicit when-not guidance versus other siblings, but the corpus scoping sentence effectively excludes private uploads.
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.
aggregate_entitydescribe_queryable_entitiesget_library_documentget_screen_joblist_queryable_entitiespingquery_entityscreen_driversscreen_earningssearch_public_libraryLicensed, cited financial data for AI agents: news, filings, transcripts, research and tearsheets.
Research layer for AI agents: stock theses, filing Q&A with page cites, monitoring. Research-only.
US stock market data for AI agents: SEC filings, financials, insider trades, 13F, options, macro.
Primary-source SEC filing intelligence and financial/disclosure reconciliation for AI agents.
Add one secure layer between your agents and this server.
