Skip to main content
Glama

CatchAll

by com.newscatcherapi

submit_query

Create a new CatchAll processing job from a natural-language query.

Use when:

  • You want to start a new CatchAll web research run from a user query.

  • You want the API to fetch/process sources and then return structured results.

Do not use when:

  • You want status for an existing job (use get_job_status).

  • You want records for an existing job (use pull_results).

Key rules:

  • query is required.

  • You can submit with only query; omitted optional fields (validators, enrichments, start_date, end_date) are auto-selected/generated by the API.

  • Optional fields are independent: you can pass any subset (for example, custom validators but no enrichments), and omitted fields are still auto-selected/generated.

  • When connected_dataset_ids is set, the query must describe the topic or event type only (e.g. "M&A activity", "regulatory filings", "executive changes"). Do NOT write things like "for my companies", "for the selected list of companies", or "news about my watchlist" — the entity filtering is applied automatically by the connected dataset. Mentioning companies in the query when a dataset is attached is redundant and degrades retrieval quality.

  • When connected_dataset_ids is set, entity-relevance validators (e.g. company_is_primary_subject) are generated automatically by the API. Do NOT add them manually to validators — they are redundant and may conflict with the auto-generated ones. Only pass validators that describe the event or topic, not entity filtering.

  • start_date and end_date filter by web page discovery date, not event date.

  • Discovery dates and extracted event dates can differ. For event-time accuracy, use event-focused validators/enrichments and verify event_date in pulled results.

  • end_date must be after start_date.

  • Dates outside your plan lookback limits return API 400.

  • limit controls processed record count (cost-affecting). Omit it to retrieve everything up to your plan's maximum. If provided, must be >= 10.

  • validators / enrichments may be passed either as arrays or as JSON-string arrays (for client compatibility).

  • validators[].type must be boolean (if omitted, it defaults to boolean).

  • enrichments[].type supported values: text, number, date, option, url, company.

Basic examples:

  • validators: [{"name":"is_acquisition_event","description":"true if page describes an acquisition","type":"boolean"}]

  • enrichments: [{"name":"acquiring_company","description":"Extract acquiring company","type":"company"},{"name":"deal_value","description":"Extract announced deal value","type":"number"}]

Next step:

  • Save the returned job_id.

  • Poll get_job_status and call pull_results (partial results can appear before completion).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
modeNoOptional job processing mode: `"lite"` (faster, lower cost, less detail) or `"base"` (default, full extraction). If omitted, the API defaults to `"base"`.
limitNoOptional processing cap (minimum 10); affects cost. Omit to retrieve everything up to your plan's maximum.
queryYesPlain text search intent (required).
schemaNoOptional advanced custom JSON schema string that overrides the default extraction schema. Use `initialize_query` to discover a suitable schema.
api_keyNoCatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
contextNoOptional guidance on what to prioritize (for example, target entities, event types, and specific data points you want captured in enrichments). If a company dataset will be attached, note that entity-relevance validators (e.g. `company_is_primary_subject`) will be auto-generated — do not ask for them here. Do not mention things like "company list will be attached".
end_dateNoOptional ISO 8601 UTC end of search window.
project_idNoOptional project ID to associate this job with.
start_dateNoOptional ISO 8601 UTC start of search window.
validatorsNoOptional custom boolean validators (`name`, `description`, `type`), as array or JSON-string array. When `connected_dataset_ids` is set, do NOT include entity-relevance validators such as `company_is_primary_subject` — the API generates those automatically. Only add validators that describe the event or topic (e.g. `is_acquisition_event`).
enrichmentsNoOptional custom enrichments (`name`, `description`, `type`), as array or JSON-string array.
webhook_idsNoOptional list of webhook IDs to notify when the job completes (max 5 per job). Use `list_webhooks` / `create_webhook` to get IDs.
ed_score_minNoOptional minimum entity-domain relevance score (1-10). Only relevant when `connected_dataset_ids` is set.
ed_association_typeNoOptional filter on how strongly a watchlist entity must appear in each event. Only relevant when `connected_dataset_ids` is set. - `"event_associated"`: keep only events where the entity is a **direct actor** (default when connected_dataset_ids is set). - `"mention"`: keep all even where the entity is **merely referenced**.
connected_dataset_idsNoOptional list of dataset IDs whose entities narrow the retrieval scope. When set: (1) entity filtering is applied automatically — do NOT mention the company list or watchlist in `query`; (2) entity-relevance validators such as `company_is_primary_subject` are generated automatically — do NOT add them to `validators`. `ed_score_min` defaults to 2 if not provided.
fetch_all_watchlist_newsNoWhen `True`, retrieves **all** news for connected watchlist entities without applying topic filtering from `query`. Requires `connected_dataset_ids` to be set. Default: `False`.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

TDQS

A5/5.0
Behavior5/5

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

Without annotations, the description carries full responsibility for behavioral disclosure. It extensively explains auto-selection of optional fields, interaction with `connected_dataset_ids`, date semantics (discovery vs event date), parameter flexibility (arrays or JSON strings), and next steps. This exceeds typical transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear headings and bullet points. Each sentence adds value, and it is front-loaded with the primary purpose. Despite length, it is concise relative to the complexity of the tool.

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

Completeness5/5

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

Given 16 parameters and an existing output schema, the description covers all necessary aspects: usage context, parameter interactions, constraints, examples, and post-submission workflow. It leaves no critical gaps for an AI agent to misuse the tool.

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

Parameters5/5

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

Schema description coverage is 100%, but the description adds crucial context beyond the schema, such as rules for `validators` and `enrichments` when datasets are attached, the meaning of `ed_score_min` and `ed_association_type`, and the behavior of `fetch_all_watchlist_news`. This greatly aids correct parameter usage.

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

Purpose5/5

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

The description begins with 'Create a new CatchAll processing job from a natural-language query,' clearly stating the verb and resource. It distinguishes itself from sibling tools like `get_job_status` and `pull_results` by specifying when to use each.

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

Usage Guidelines5/5

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

Explicit 'Use when' and 'Do not use when' sections provide clear context. It advises against using for job status or results, directing to appropriate alternatives. The description also includes detailed rules and examples for correct usage.

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

All CatchAll toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A3.6/5.0
Disambiguation4/5

Most tools have distinct purposes, but some pairs like create_dataset vs create_dataset_from_csv or pull_results vs pull_job_csv could cause confusion. However, descriptions clarify differences.

Naming Consistency4/5

Tools follow a consistent verb_noun pattern (e.g., create_dataset, list_datasets) with minor exceptions like append_csv_to_dataset and pull_job_csv. Overall predictable.

Tool Count3/5

60 tools is high for an MCP server, but the domain (web research, job processing, multiple resource types) justifies the count. Still borders on excessive.

Completeness5/5

The server offers full CRUD for datasets, entities, monitors, projects, webhooks, plus job submission, status polling, result retrieval (JSON/CSV), webhook management, and health endpoints. No obvious gaps.

Resources