Grounded financial research for agents: filings, transcripts, news across US and Asia markets.
Scored across 10 tools
Each tool targets a distinct resource or action: query vs aggregate vs describe vs list; screen_drivers vs screen_earnings are clearly separate domains. Descriptions explicitly cross-reference to avoid confusion, e.g., query_entity directs GROUP BY to aggregate_entity.
All names use snake_case with a consistent verb_noun pattern (e.g., query_entity, get_screen_job, search_public_library), with only 'ping' as a trivial exception. The convention is predictable throughout.
10 tools is well-scoped for a data query and screening server; each tool serves a clear purpose without redundancy. No tool feels extraneous or missing in the core set.
Core operations for querying, aggregating, screening, and retrieving documents are present. Minor gaps exist, such as job cancellation or listing screen jobs, but these are workable around and don't block primary workflows.
Read one Queryable Entity as a GROUP BY aggregate. Returns one page of groups. Call list_queryable_entities first, then describe_queryable_entities. 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. Public fields: entity, aggregates, group_by, filters, filter_logic, having, sort, joins, limit. Functions: COUNT, SUM, AVG, MIN, MAX. filters = WHERE; having = HAVING. Pass IN lists on filter.value. Do not pass value_path. A full page sets truncated=true. This call does not scan the full universe.
| 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?
Adds meaningful behavior beyond the readOnly/idempotent annotations: pagination semantics (one page of groups, truncated=true when a full page), the no-full-universe-scan limitation, and IN-list/value_path constraints. Does not cover auth/user-scoped behavior or rate limits, so not 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?
Front-loads the core operation and then packs references efficiently, but the long entity enumeration and terse field listing make it read as a run-on rather than cleanly structured guidance. Every sentence carries information, but the density is high.
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?
Covers the key gaps for a 9-param read-only tool with no output schema: valid entities, functions, filter/having semantics, pagination truncation, and universe-scan limits. Output shape (page of groups) is described at a high level but its fields are not, which is a minor 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 the burden and does: it defines the public fields, maps filters=WHERE and having=HAVING, declares valid functions (COUNT, SUM, AVG, MIN, MAX), and states filter.value is where IN lists go and that value_path is forbidden. It does not document sort/joins/limit semantics in depth, hence not a 5.
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 (Read as GROUP BY aggregate) and resource (Queryable Entity), and explicitly positions it relative to siblings by instructing to call list_queryable_entities then describe_queryable_entities first. Clearly distinguishable from query_entity.
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?
Explicit prerequisites are named (call list_queryable_entities, then describe_queryable_entities), alternatives at the field level are hinted (query_entity for non-grouped reads), and the universe-scan caveat is stated. Nothing is left to inference for when to reach for this tool.
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 a comma-separated list of names (for example company,file). Returns field names, types, descriptions, operators, and select, filter, and sort flags.
| Name | Required | Description | Default |
|---|---|---|---|
| entity | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds real value beyond them by disclosing the dependency chain and the return payload (field names, types, descriptions, operators, select/filter/sort flags), which matters because there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the core purpose and then the call-order constraints. The final sentence lists return fields, which is justified given the absence of an output schema, though it is slightly list-like rather than prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, single-parameter introspection tool with no output schema, the description covers purpose, ordering, input format, and return shape. Nothing critical is missing; only richer detail on error behavior or partial-name handling would raise it further.
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% for the single 'entity' parameter, so the description must compensate. It does: 'Pass a comma-separated list of names (for example company,file)' supplies both the wire format and a concrete example that the bare schema string type lacks.
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 ('Describe the schema of ... Queryable Entities') and explicitly differentiates itself from list_queryable_entities, query_entity, and aggregate_entity by naming them. 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 constraints: call list_queryable_entities first, and call this before query_entity and aggregate_entity. This is prescriptive when/when-not guidance tied to named siblings rather than vague context.
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. Returns names, descriptions, aliases, and join_targets.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description still adds value by disclosing the returned fields (names, descriptions, aliases, join_targets) and clarifying the read scope. It does not mention pagination or limits, which is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, zero waste, front-loaded with the purpose followed by the ordering instruction and the return contents. 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?
No output schema exists, so the description usefully enumerates the returned fields, and it establishes the call ordering relative to the query tools. For a parameterless, read-only discovery tool 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?
The tool takes zero parameters, so parameter semantics are moot and the baseline of 4 applies. Nothing in the description misrepresents the parameter surface.
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 Queryable Entities') and adds the scoping qualifier 'this MCP may read'. It is immediately distinguishable from siblings like query_entity, describe_queryable_entities, and aggregate_entity 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?
Explicitly states when to call it and names the three alternative tools it should precede ('Call this before describe_queryable_entities, query_entity, and aggregate_entity'). This is exactly the routing guidance an agent needs.
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 Queryable Entity. Returns one page of rows. Call list_queryable_entities first, then describe_queryable_entities. 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. Public fields: entity, select, filters, filter_logic, sort, joins, limit. Pass IN lists on filter.value. Do not pass value_path. A full page sets truncated=true and may include next_hint. For GROUP BY aggregates (COUNT, SUM, AVG, MIN, MAX), 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?
Discloses two key behavioral facts beyond the read-only annotations: pagination behavior ("Returns one page of rows", truncated=true, next_hint) and a prohibition on value_path. Annotations already cover readOnly/idempotent/destructive status, so the added pagination and value_path context is the right complement. Could say more about limit semantics or default page size.
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?
Very dense, front-loaded with action verb and pagination, then workflow guidance, then parameter guidance, then the aggregate alternative. The 20-entity list is lengthy but serves to prevent guessing, so it earns its place. Minimal waste overall.
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 correctly explains return shape (page of rows, truncated, next_hint) and pagination. No annotations beyond read-only, so the description carries behavior and it does. A more detailed filter/join syntax summary or default page size detail would make it 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 0%, so the schema names parameters without explaining them. The description compensates by listing the public fields (entity, select, filters, filter_logic, sort, joins, limit) and explicitly stating how to pass lists (on filter.value) and what not to pass (value_path). Some parser-specific detail (filter op vs operator duplication) is left unaddressed.
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 Queryable Entity"), and explicitly distinguishes itself from sibling aggregate_entity by declaring GROUP BY aggregates are handled there. It also names the sibling tools that precede it (list_queryable_entities, describe_queryable_entities).
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?
Explicit workflow ordering: "Call list_queryable_entities first, then describe_queryable_entities." It also states what not to use it for (GROUP BY aggregates) and directs to aggregate_entity. Both when-to-use and when-not-to-use are covered.
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.
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.
Primary-source SEC filing intelligence for AI agents, with exact evidence and provenance.
Add one secure layer between your agents and this server.
