Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.
Scored across 11 tools
Most tools have clearly distinct purposes: catalog search/describe, explicit call, composed fetch, snapshots, timeseries, entity resolution, and KYB/sanctions screening. The main overlap is fetch_data versus call_endpoint (plus search_endpoints), but the descriptions explicitly frame fetch_data as a one-step convenience wrapper.
All names use consistent snake_case and mostly follow a readable verb_noun pattern (call_endpoint, describe_endpoint, get_snapshot, list_sources, resolve_entity, search_endpoints). The two sugra_entity_* names share their own clear prefix pattern rather than breaking convention.
11 tools is well-scoped for an API gateway plus composed data/compliance layer. Each tool earns its place by covering a distinct stage: discovery, description, invocation, composed retrieval, entity resolution, and screening.
The surface covers the core lifecycle well: list/search/describe endpoints, call or fetch data, get snapshots and timeseries, resolve entities, and perform KYB/sanctions checks. Minor gaps remain around explicit batch invocation or pagination helpers, but agents can work around them via call_endpoint parameters.
Call a Sugra API endpoint by operation_id from the bundled catalog.
Plan calls with describe_endpoint's agent_hints: duration_class "fast" usually responds in under ~2s, "slow" usually 1-5s and occasionally 15s+ on a cold upstream, "heavy" can exceed the gateway timeout - keep parallel calls within max_concurrency and prefer small batches. Bulk endpoints bill 1 request credit per body item. Failures return structured errors {error, reason, status_code, elapsed_ms, retry_hint}; after "upstream_timeout" a single retry often succeeds because the aborted attempt warms upstream caches.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | JSON request body for a POST operation, matching the request_body_schema returned by describe_endpoint(operation_id): a JSON object for most operations, or a JSON array when that schema's top-level type is array. Omit for GET operations. | |
| limit | No | Bounds ONLY the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). When data has no such single list but every one of its values is an object holding exactly one list named observations, limit bounds each data.<key>.observations list on its own (records_path data.*.observations); fields there still names keys of data. Otherwise, no such list, or several, means the limit does not apply. Keys beside the list such as total and count are not rewritten, and lists nested inside records are never truncated. limit keeps the newest N records when every record carries one date or period key in one format and the list runs one way by it, else the first N, and meta.shaped reports limit_applied, records_path and, for a bounded records list, order (asc, desc or unknown) and kept_end (newest or first), as maps by name for sibling sub-series. | |
| fields | No | Optional projection of keys to keep on each record of the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). Keys beside that list such as total and count stay. If a field names a key of data itself, or of a payload without data, that object is projected instead; an object data without such a list is otherwise kept whole. Dotted paths (geo.city) walk nested objects. If no field matches, nothing is removed. meta.shaped reports fields_applied, fields_unmatched and records_path. Omit to keep every key. | |
| params | No | Query and path parameters for this operation_id. Keys and types are operation-specific - call describe_endpoint(operation_id) first to get the exact parameter names, types, and examples. Omit if the operation takes none. A key the operation does not declare returns error unknown_parameters with the accepted names and did_you_mean, before any request is made. | |
| include_raw | No | If true, attach the original unshaped payload under raw when it fits the size cap; otherwise meta.raw_omitted explains why. Default false. | |
| operation_id | Yes | Catalog operation_id to call, from search_endpoints (or from list_toolsets drill-down). Call describe_endpoint on it first for the parameter names. Unknown ids return error unknown_operation_id before any request is made. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial extra behavior: duration classes with typical latencies, cold-upstream timeouts, concurrency limits, per-body-item billing, the structured error shape {error, reason, status_code, elapsed_ms, retry_hint}, and the cache-warming retry insight. This is exactly the kind of context annotations cannot 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?
Purpose is front-loaded in the first sentence, followed by high-density operational guidance. The paragraph runs long and packs several distinct facts (durations, concurrency, billing, errors, retry), but almost every sentence carries unique value.
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 an output schema present, return values need not be explained, and the description still adds the error shape and retry guidance. For a broad dispatch tool over an external catalog, this is nearly complete; it could add explicit routing versus sibling data tools but covers the essentials.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantic meaning beyond the schema: bulk endpoints bill 1 request credit per body item, and failures return a defined error envelope that ties to retry behavior. It also reinforces the describe_endpoint dependency for params rather than restating field types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Call a Sugra API endpoint by operation_id from the bundled catalog.' This clearly identifies the action and the catalog-scoped identifier. It doesn't explicitly distinguish itself from siblings like fetch_data or get_timeseries, but the operation_id/catalog framing is distinctive enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete context: plan calls with describe_endpoint's agent_hints, keep parallel calls within max_concurrency, prefer small batches, and retry once after upstream_timeout. It doesn't state explicit exclusions against sibling tools like fetch_data or get_snapshot, but the planning guidance is actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe one Sugra API endpoint by operation_id.
Includes agent_hints (duration_class fast/slow/heavy, max_concurrency,
bulk billing) so you can budget timeouts and parallelism before calling.
POST endpoints with a JSON body also carry request_body_schema (the
resolved JSON schema) - construct the body argument from it instead
of guessing key names. Call this after search_endpoints and before
call_endpoint when you need the exact parameter names and examples.
| Name | Required | Description | Default |
|---|---|---|---|
| operation_id | Yes | Catalog operation_id from search_endpoints (or from list_toolsets drill-down). Unknown ids return error unknown_operation_id. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds genuine behavioral value: it discloses that the response includes agent_hints (duration_class, max_concurrency, bulk billing) and that POST endpoints carry request_body_schema, which instructs the agent how to construct the body argument. This goes beyond the structured annotations without contradicting them.
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 tightly structured: purpose first, then valuable behavioral hints, then workflow guidance. Every sentence earns its place, and there is no filler or repetition of the tool's title.
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 simple single-parameter, read-only tool with a rich output schema, the description covers everything needed to call it correctly: what it does, what the response contains, how to obtain operation_id, and where it fits in the workflow. The output schema covers return-value details, so nothing important 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 100% for the single parameter operation_id, and the schema already explains its provenance and error behavior. The description does not add much new parameter-level meaning beyond mentioning that exact parameter names come from this tool, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Describe one Sugra API endpoint by operation_id.' It is clearly differentiated from siblings by placing it in a workflow between search_endpoints and call_endpoint, so an agent can tell it apart from search, call, and data-fetch tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it: 'Call this after search_endpoints and before call_endpoint when you need the exact parameter names and examples.' This provides both temporal sequencing and a decision condition, making the usage context unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One-step fetch: find the best Sugra endpoint for the query and call it.
Combines search_endpoints + call_endpoint into a single round trip. Use this when you want data without manually picking an operation_id. The full search_endpoints + describe_endpoint + call_endpoint dance is still available when you need explicit control, but for most natural-language queries this tool is enough.
Behavior:
Search the bundled catalog for the query. Top match wins.
If the matched endpoint has required parameters and they are all
provided in params, call it and return the response.
If required parameters are missing, return the candidate endpoints
and the missing-params list so the LLM can retry with the correct
params dict on the next call.
If the query names a country and the match takes a country or
countries param that params leaves unset, return needs_params
for it with query_countries (ISO2) instead of running the match
without that filter.
Examples:
fetch_data("US CPI inflation", params={"series_id": "CPIAUCSL"})
runs fred_series_series_id (/api/v1/fred/series/CPIAUCSL) and returns
observations.
fetch_data("Bitcoin price")
runs onchain_bitcoin_price, which takes no params.
fetch_data("Latest financial news")
runs news_latest, which has no required params.
Only the top match runs, and a param it does not declare returns error
unknown_parameters. For one coin's price, name the operation:
call_endpoint("crypto_coin_id_price", params={"coin_id": "bitcoin"}).
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | JSON body for an auto-selected POST operation; the tool returns the request_body_schema to fill when the match needs one. Pass a JSON object or a JSON array as that schema's top-level type dictates. | |
| limit | No | Bounds ONLY the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). When data has no such single list but every one of its values is an object holding exactly one list named observations, limit bounds each data.<key>.observations list on its own (records_path data.*.observations); fields there still names keys of data. Otherwise, no such list, or several, means the limit does not apply. Keys beside the list such as total and count are not rewritten, and lists nested inside records are never truncated. limit keeps the newest N records when every record carries one date or period key in one format and the list runs one way by it, else the first N, and meta.shaped reports limit_applied, records_path and, for a bounded records list, order (asc, desc or unknown) and kept_end (newest or first), as maps by name for sibling sub-series. | |
| query | Yes | Natural-language request for data (examples: 'US CPI', 'Bitcoin price', 'latest news'). The tool picks the top catalog match and calls it. If required params are missing it returns needs_params instead of guessing. | |
| fields | No | Optional projection of keys to keep on each record of the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). Keys beside that list such as total and count stay. If a field names a key of data itself, or of a payload without data, that object is projected instead; an object data without such a list is otherwise kept whole. Dotted paths (geo.city) walk nested objects. If no field matches, nothing is removed. meta.shaped reports fields_applied, fields_unmatched and records_path. Omit to keep every key. | |
| params | No | Parameters for the auto-selected endpoint. If omitted and the best-match endpoint has required parameters, the tool returns that endpoint's required_parameters and examples so you can retry with them filled in. | |
| include_raw | No | If true, attach the original unshaped payload under raw when it fits the size cap; otherwise meta.raw_omitted explains why. Default false. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false), yet the description adds substantial behavior beyond them: top-match-wins selection, the needs_params retry contract, the unknown_parameters error, the country-param auto-injection rule, and the fact that only the top match runs. This is genuinely useful operational detail not derivable from the 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?
Front-loaded with the core purpose and alternative routing, then structured as numbered Behavior steps and Examples. It is longer than strictly necessary (three examples plus a trailing counter-example), but every section is load-bearing rather than 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?
With an output schema present and full annotation coverage, the description need not explain return values; instead it supplies exactly the missing pieces — selection behavior, error/retry contracts, and alternative routing. An agent has everything needed to call this correctly on the first try.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description still adds meaning by explaining the retry flow for `params` (returns required_parameters and examples), the `query` natural-language contract, and the unknown_parameters failure mode. It does not restate the schema's extensive limit/fields semantics, which the schema already carries.
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 ('fetch data') and immediately distinguishes itself from siblings: it 'Combines search_endpoints + call_endpoint into a single round trip.' The agent can tell it apart from search_endpoints, describe_endpoint, and call_endpoint 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?
Explicit when-to-use ('when you want data without manually picking an operation_id'), when the alternative is warranted ('the full search_endpoints + describe_endpoint + call_endpoint dance is still available when you need explicit control'), and a concrete fallback for a specific case ('For one coin's price, name the operation: call_endpoint(...)'). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Composed current view of an entity via a named recipe.
Executes a fixed server-side recipe (company_snapshot, etf_snapshot, quote_snapshot, macro_indicator_snapshot, macro_calendar, earnings_snapshot, debt_snapshot) and returns one envelope with freshness, provenance, per-component coverage, and billing. Composed calls charge the recipe's fixed cost (1-2 units) from the daily quota. status "partial" means an optional component was unavailable - the present components are still trustworthy; honor the freshness block (stale=true means the data aged past its budget); for macro_calendar, entity is accepted but does not filter the calendar.
Args: recipe: Recipe name from the fixed manifest. entity: Entity dict from resolve_entity ({"namespace": ..., "ids": ...}).
| Name | Required | Description | Default |
|---|---|---|---|
| entity | Yes | Entity dict from resolve_entity ({namespace, ids}). Extra keys are ignored. | |
| recipe | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond the annotations: quota/billing cost (1-2 units), the meaning of 'partial' status, the freshness block contract (stale=true aged past budget), and the macro_calendar edge case where entity is accepted but does not filter. The annotations only cover read-only/idempotent safety, so this description carries the real behavioral load.
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, followed by execution behavior then args. Dense but every sentence adds operative detail; no filler, though it is on the longer side for a two-parameter tool.
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?
Output schema covers the returned envelope, so return-value detail is not needed here, and the description still covers billing, partial status, freshness, and the macro_calendar exception. Combined with safety annotations, 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?
At 50% schema coverage the description must compensate, and it does: it documents recipe as coming from a fixed manifest and lists the valid recipe values (acting as an enum substitute), plus clarifies entity's expected shape from resolve_entity. It stops short of explaining semantics of the ids map.
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 ('Composed current view of an entity via a named recipe') and enumerates the exact recipe names, which lets an agent distinguish it from siblings like get_timeseries, fetch_data, and call_endpoint 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 clear usage context: composed calls charge 1-2 units from the daily quota, status 'partial' is explained, and freshness/staleness must be honored. However, it never explicitly names an alternative sibling or a when-not-to-use condition, so routing guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bounded timeseries for an entity: price, macro_series, etf_flows or etf_monthly_flows.
Returns points oldest-first with an explicit downsampling flag when the raw series exceeded max_points. Times are UTC. Costs 1 unit per call.
The two ETF flow metrics answer different questions and are not
interchangeable. etf_flows is an ESTIMATE at filing cadence: one point
per SEC filing refresh, so t is a filing date and even a wide window
yields a handful of points. etf_monthly_flows is the fund's own
creations and redemptions from its NPORT-P filing, so t is a calendar
month (YYYY-MM) and each point carries the three filed components -
sales, reinvestment, redemption - beside the net.
Two things to read before quoting etf_monthly_flows. NPORT-P is filed per
SERIES, so for a fund with more than one share class the figures cover
every class and the payload says so in multi_class_series; where the
class count is unknown it says class_scope instead of staying silent.
And a fund that files no NPORT-P at all, such as a commodity trust, is not
an error: the call returns status partial with an empty point list and
a reason.
Args: metric: One of price / macro_series / etf_flows / etf_monthly_flows. entity: Entity dict from resolve_entity ({"namespace": ..., "ids": ...}). granularity: Requested point granularity (default "1d"). max_points: Hard cap on returned points (default 500).
| Name | Required | Description | Default |
|---|---|---|---|
| entity | Yes | Entity dict from resolve_entity ({namespace, ids}). Extra keys are ignored. | |
| metric | Yes | ||
| max_points | No | ||
| granularity | No | 1d |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive. The description adds substantial behavioral details: cost (1 unit per call), UTC times, oldest-first ordering, downsampling flag, partial status with reason, multi_class_series/class_scope nuances, and the not-an-error case for missing NPORT-P. No contradictions.
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 verbose but every paragraph adds necessary nuance. It front-loads the core functionality and then details edge cases and parameter meanings. It avoids fluff and is organized with an Args section, making it scannable despite its length.
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 a rich output schema, the description explains the non-obvious return conditions (partial status, downsampling, cost, timezone) that are not self-evident from schema. It covers both happy and edge cases, making the tool complete for correct invocation and interpretation.
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 low (25%), and the description compensates by explaining metric semantics in depth, including the filing cadence difference, the meaning of t for each metric, and the components in etf_monthly_flows. It also clarifies entity comes from resolve_entity and notes defaults for granularity and max_points.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Bounded timeseries for an entity') with explicit metric types (price, macro_series, etf_flows, etf_monthly_flows). It clearly distinguishes from siblings by enumerating what it returns and the downsampling behavior, leaving no ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly differentiates between etf_flows and etf_monthly_flows, explaining when each answers a different question and when to expect partial results. It does not contrast with sibling tools like get_snapshot, but within its domain it gives clear context on metric selection and edge cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List source families in the bundled catalog with endpoint counts.
Use the family names as the source filter on search_endpoints. This does not call the Sugra API.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds non-obvious behavioral context by stating 'This does not call the Sugra API,' indicating a local, low-cost operation beyond what the annotations 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?
The description is three short sentences with no filler. It front-loads the core purpose, then gives a practical usage hint, then a clarifying behavioral note. 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?
The tool is simple: zero parameters, an output schema is present, and annotations cover safety and idempotency. The description adds the only missing context (localiveness and how to use the result), making it complete for correct invocation.
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 has zero parameters, so the baseline is 4. The description doesn't attempt to explain parameters because none exist; instead it focuses on the meaning of the returned family names, which is relevant downstream.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List source families in the bundled catalog with endpoint counts.' It clearly distinguishes this from siblings like search_endpoints or list_toolsets by naming the exact object being listed and the data returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides actionable guidance: 'Use the family names as the source filter on search_endpoints.' It also clarifies that this tool does not call the Sugra API, indicating when it is appropriate for local/bundled data. It gives clear context but doesn't spell out explicit exclusion scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List catalog groups with endpoint counts and short descriptions.
Use the group names as the toolset filter on search_endpoints. This does not call the Sugra API; it reads the bundled catalog.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description adds value by stating that this reads the bundled catalog and does not call the Sugra API. That is a meaningful behavioral fact not encoded in structured fields.
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 three short sentences with no filler. It front-loads the core purpose, then adds the use-the-result guidance, then a useful offline behavior note. 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?
Given zero parameters, existing annotations, and an output schema, the description tells an agent everything it needs to call the tool correctly and what to do with the results. There is no missing prerequisite, filtering instruction, or safety concern.
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 zero parameters, so the baseline is 4. The description adds some return-shape context (endpoint counts and short descriptions), which is sufficient for a parameterless listing tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('List catalog groups') and the output shape ('with endpoint counts and short descriptions'). It clearly distinguishes this from search_endpoints by describing the output as a filtering input for that tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly describes the intended downstream use: 'Use the group names as the toolset filter on search_endpoints.' It also clarifies that this reads the bundled catalog and does not call the Sugra API, which gives clear context. It does not explicitly name when-not-to-use or list alternatives, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve free text to a canonical market or macro entity.
Turns a ticker, company name, macro indicator, coin, or currency pair into
the agent plane's {namespace, ids} entity for use with get_snapshot and
get_timeseries. A cross-namespace collision (e.g. a ticker that is both an
equity and a coin) returns status "ambiguous" with ranked candidates and
NEVER silently picks one; pass type_hint (e.g. "equity", "etf", "coin") to
narrow the universe. Crypto aliases resolve too (e.g. "bitcoin" -> the
BTC coin entity). Status "low_confidence" means the best match cleared
resolution but scored weakly - verify the returned entity before
building on it, or re-query with a more specific name or type_hint. For compliance KYB lookups by LEI/VAT or sanctions
screening use sugra_entity_lookup / sugra_entity_screen instead - this tool
is for market-data entities.
Args: query: Free-form text - ticker, company, indicator, coin, or pair. type_hint: Optional namespace hint narrowing resolution.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| type_hint | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals important behavior: collision returns 'ambiguous' with ranked candidates and never silently picks, type_hint narrows the universe, crypto aliases resolve, and low_confidence is a weak-match signal with explicit advice to verify. This enriches the agent's understanding of runtime responses significantly.
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 informative yet structured: it leads with a clean one-sentence purpose, gives necessary behavioral nuances, then an Args list. Each sentence adds meaningful guidance—no filler. The explicit alternative pointer and the low_confidence example are useful and not redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's disambiguation behavior, the description adequately covers its main use case, edge cases (collisions, low confidence), and relationships to companion tools. The output schema exists, so the description need not enumerate return details, but it explains the semantic value that the agent needs for correct invocation and post-result verification.
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 parameter semantics. The Args section explains query as free-form text and type_hint as an optional namespace narrowing hint, with concrete examples ('equity', 'etf', 'coin'). While the type_hint examples are helpful, the description could be slightly more precise about accepted type_hint values beyond those examples, but it is still well above a baseline because the description compensates for the missing 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?
The description opens with a specific verb+resource pair: 'Resolve free text to a canonical market or macro entity.' It clearly explains the tool's output (namespace/ids entity) and its use for get_snapshot/get_timeseries, setting it apart from sibling tools including the compliance-oriented sugra_entity_lookup/screen.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit alternatives: for compliance KYB lookups use sugra_entity_lookup / sugra_entity_screen instead. It also explains when to use type_hint to narrow an ambiguous resolution and advises verifying low_confidence results. This covers when and when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the bundled Sugra endpoint catalog by natural-language query.
Use this to pick an operation_id. It does not fetch data. Typical loop:
search_endpoints(query) -> ranked hits with required_parameters
describe_endpoint(operation_id) -> params, request_body_schema, agent_hints
call_endpoint(operation_id, params=..., body=...) or fetch_data(query, params=...)
Filter with toolset or source only after list_toolsets / list_sources; a misspelled filter is an error, not a silent empty result.
Examples:
search_endpoints("US CPI inflation")
search_endpoints("AAPL price", toolset="markets")
search_endpoints("container ship AIS", toolset="network")
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum ranked hits to return. Default 10. Does not call the Sugra API; this only bounds the catalog search list. | |
| query | Yes | Natural-language search over the bundled catalog. Name the instrument, series, place, or task (examples: 'US CPI', 'AAPL quote', 'North Sea AIS'). Returns ranked operation_id hits with required_parameters. Then call describe_endpoint on a hit before call_endpoint. | |
| source | No | Optional source-family filter as listed by list_sources (macro, markets, ...). An unknown value returns error unknown_source with known_sources. | |
| toolset | No | Optional catalog group filter (markets, macro, news, network, ...). Call list_toolsets for the live names. An unknown value returns error unknown_toolset with known_toolsets rather than an empty hit list. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond that: it searches a bundled catalog rather than fetching live data, returns ranked hits with required_parameters, and yields specific errors like unknown_toolset with known_toolsets for invalid filters. This makes the tool's runtime behavior transparent.
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 well-structured: a one-sentence core statement, a compact numbered workflow, a crucial filter warning, and three concrete examples. There is no filler, and the most important behavioral distinction ('does not fetch data') is front-loaded.
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?
The description is complete for this tool's complexity. It explains the return shape, the recommended follow-up steps, filter semantics, error behavior, and gives examples. Since an output schema exists, further return-value detail is unnecessary. An agent has everything needed to invoke the tool 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 100%, so the schema already documents all parameters thoroughly. The description reinforces key points such as query being a natural-language search and source/toolset being optional filters, but it does not add substantial parameter meaning beyond the schema. Baseline 3 is appropriate because the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Search the bundled Sugra endpoint catalog by natural-language query.' It also clarifies the tool's role in the workflow ('Use this to pick an operation_id') and explicitly distinguishes it from data-fetching tools ('It does not fetch data'). This fully separates it from siblings like call_endpoint and describe_endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use the tool and how it fits into a typical loop with describe_endpoint and call_endpoint/fetch_data. It also warns about filter usage: 'Filter with toolset or source only after list_toolsets / list_sources' and explains misspelled filters produce errors, not empty results. This is clear, actionable usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve an entity by identifier and return its composed KYB envelope.
anchor is lei (Legal Entity Identifier, resolved via the GLEIF registry)
or vat (EU VAT number, validated via the EU VIES service). The result
weaves identity, a sanctions screening signal, and - on request - ownership
and adverse-media slices.
The screening verdict is a SCREENING SIGNAL, not a compliance determination,
and any PEP / adverse-media content is supplementary and non-comprehensive.
The disclaimer field carries this and is always present.
Output is COMPACT by default to protect the agent context budget:
{entity:{name, anchor, value, status, country}, screening:{status, top_matches:[...3], hit_count}, ids:{...}, disclaimer}. Pass include to
opt INTO fuller per-slice detail, e.g.
include=["ownership","adverse_media"] adds those slices in full form.
On a bad anchor or an API error this returns a clean {error, detail} dict
rather than raising, so the agent can branch on result.get("error").
Args:
anchor: Identifier type, one of lei or vat.
value: The identifier value (the 20-char LEI code or the VAT number).
include: Optional list of fuller slices to add, e.g.
["ownership", "adverse_media"]. Omit for the compact default.
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | The identifier value: 20-character LEI or the VAT number. | |
| anchor | Yes | Identifier type: lei (GLEIF) or vat (EU VIES). | |
| include | No | Optional fuller slices to add, e.g. ownership, adverse_media. Omit for the compact default. profile and screening are already in the compact core and are not extra slices. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal read-only/idempotent behavior, and the description adds substantial behavioral detail: compact-by-default output to protect context budget, a clean {error, detail} dict instead of exceptions, always-present disclaimer, and the caveat that screening is a signal rather than a compliance determination. This goes well beyond the 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?
The description is front-loaded with purpose, then gives the output contract, error behavior, and parameter semantics in a clear, labeled structure. Every sentence earns its place without padding.
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 lookup tool, the description covers input constraints, return shape, optional parameters, error behavior, and important caveats. With the annotations and output schema available, nothing essential is missing for an agent 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?
Even though schema coverage is 100%, the description adds real semantic value: it explains that lei resolves via GLEIF and vat via VIES, specifies the value formats, and clarifies that include opts into fuller slices while the default is compact. This materially improves correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Resolve an entity by identifier') and names the concrete deliverable ('composed KYB envelope'), so an agent can tell what the tool does. However, it does not explicitly distinguish this tool from siblings like sugra_entity_screen or resolve_entity, so it misses the top differentiator.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context: identifier-based lookup with lei/vat, optional include slices, and the compact-vs-full output behavior. It also tells the agent how to handle errors by branching on result.get('error'). It does not state when not to use this tool or name an alternative, but the guidance given is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Screen a person or organization name against the Sugra sanctions corpus.
Returns a SCREENING SIGNAL, not a compliance determination. Sugra is a
technology provider, not a sanctions authority or consumer reporting agency.
PEP and adverse-media coverage is supplementary and non-comprehensive - a
clear result is not proof of absence, and a hit is a candidate match to
review, not a finding.
Output is COMPACT to protect the agent context budget:
{status, matches:[{name, score, list, type}], disclaimer}. The verdict
status is one of clear, review, or hit. The heavy raw fields
(match rationale, source ids, publish dates) are dropped; use the Sugra API
directly when the full screening envelope is needed.
Args: name: The person or organization name to screen (required). country: Optional ISO 3166-1 alpha-2 country to narrow the match. dob: Optional date of birth (YYYY-MM-DD) for a person. nationality: Optional nationality to narrow the match.
| Name | Required | Description | Default |
|---|---|---|---|
| dob | No | Optional date of birth for a person, YYYY-MM-DD. | |
| name | Yes | Person or organization name to screen (required). | |
| country | No | Optional ISO 3166-1 alpha-2 country to narrow the match. | |
| nationality | No | Optional nationality to narrow the match. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context: it returns a signal, not a compliance determination; it warns that a 'clear' result is not proof of absence and a 'hit' is a candidate match; and it describes the compact output structure (status, matches, disclaimer). This goes beyond the annotations by explaining the semantic limitations and output shape, though it could mention error handling or edge cases for 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?
The description is well-structured and front-loaded: it opens with the purpose, then explains the output and its rationale, then lists parameters. It is reasonably concise for the complexity of the tool, with no redundant fluff. Each paragraph earns its place, and the important caveats are prominently placed.
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?
The tool is moderately complex with disclaimers and a specific output format. The description covers the output schema (including the structure and status values), explains the non-comprehensive nature, and mentions the compactness for context budget. It lacks details on error conditions, rate limits, or exact match scoring, but the presence of an output schema and the thorough description make it largely complete for an agent to use 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?
The schema covers all four parameters with descriptions (100% coverage). The description's Args section largely repeats the schema's descriptions (e.g., country is ISO 3166-1 alpha-2, dob is YYYY-MM-DD). It adds minimal extra meaning beyond the schema, such as implying these are filters to narrow the match, but that is already implicit. Per the rubric, with high schema coverage, the baseline is 3; the description does not sufficiently enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('screen') and resource ('a person or organization name against the Sugra sanctions corpus'). It distinguishes this from a compliance determination and positions it as a screening signal, making the tool's purpose unambiguous and distinct from sibling tools like sugra_entity_lookup which likely focuses on lookup rather than screening.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when this tool is appropriate: it returns a compact screening signal to protect the agent context budget, and explicitly says to use the Sugra API directly when the full screening envelope is needed. However, it does not name sibling tools or explicitly contrast with them, so the guidance is clear but not exhaustive regarding alternative MCP tools.
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.
call_endpoint1 field changedInput schema / properties / operation_id / descriptionAdded value: +"Catalog operation_id to call, from search_endpoints (or from list_toolsets drill-down). Call describe_endpoint on it first for the parameter names. Unknown ids return error unknown_operation_id before any request is made."call_endpoint1 field changedInput schema / properties / params / descriptionPrevious value: -"Query and path parameters for this operation_id. Keys and types are operation-specific - call describe_endpoint(operation_id) first to get the exact parameter names, types, and examples. Omit if the operation takes none."New value: +"Query and path parameters for this operation_id. Keys and types are operation-specific - call describe_endpoint(operation_id) first to get the exact parameter names, types, and examples. Omit if the operation takes none. A key the operation does not declare returns error unknown_parameters with the accepted names and did_you_mean, before any request is made."call_endpoint1 field changedInput schema / properties / limit / descriptionPrevious value: -"Bounds ONLY the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). No such list, or several, means the limit does not apply. Keys beside the list such as total and count are not rewritten, and lists nested inside records are never truncated. meta.shaped reports limit_applied and records_path."New value: +"Bounds ONLY the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). When data has no such single list but every one of its values is an object holding exactly one list named observations, limit bounds each data.<key>.observations list on its own (records_path data.*.observations); fields there still names keys of data. Otherwise, no such list, or several, means the limit does not apply. Keys beside the list such as total and count are not rewritten, and lists nested inside records are never truncated. limit keeps the newest N records when every record carries one date or period key in one format and the list runs one way by it, else the first N, and meta.shaped reports limit_applied, records_path and, for a bounded records list, order (asc, desc or unknown) and kept_end (newest or first), as maps by name for sibling sub-series."fetch_data1 field changedInput schema / properties / limit / descriptionPrevious value: -"Bounds ONLY the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). No such list, or several, means the limit does not apply. Keys beside the list such as total and count are not rewritten, and lists nested inside records are never truncated. meta.shaped reports limit_applied and records_path."New value: +"Bounds ONLY the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). When data has no such single list but every one of its values is an object holding exactly one list named observations, limit bounds each data.<key>.observations list on its own (records_path data.*.observations); fields there still names keys of data. Otherwise, no such list, or several, means the limit does not apply. Keys beside the list such as total and count are not rewritten, and lists nested inside records are never truncated. limit keeps the newest N records when every record carries one date or period key in one format and the list runs one way by it, else the first N, and meta.shaped reports limit_applied, records_path and, for a bounded records list, order (asc, desc or unknown) and kept_end (newest or first), as maps by name for sibling sub-series."buy_planlist_plansbuy_planlist_plansget_snapshot7 fields changedInput schema / $defsRemoved value: -{
- "AgentEntity": {
- "description": "The agent-plane entity shape returned by resolve_entity and consumed by\nget_snapshot / get_timeseries. Extra keys from a resolve result (label,\nconfidence) are accepted and ignored - only namespace + ids are sent on.",
- "properties": {
- "ids": {
- "additionalProperties": true,
- "title": "Ids",
- "type": "object"
- },
- "namespace": {
- "title": "Namespace",
- "type": "string"
- }
- },
- "required": [
- "namespace",
- "ids"
- ],
- "title": "AgentEntity",
- "type": "object"
- }
-}Input schema / properties / entity / $refRemoved value: -"#/$defs/AgentEntity"Input schema / properties / entity / additionalPropertiesAdded value: +trueInput schema / properties / entity / descriptionAdded value: +"Entity dict from resolve_entity ({namespace, ids}). Extra keys are ignored."Input schema / properties / entity / propertiesAdded value: +{
+ "ids": {
+ "additionalProperties": true,
+ "description": "Identifier map from resolve_entity.",
+ "type": "object"
+ },
+ "namespace": {
+ "description": "Entity namespace from resolve_entity.",
+ "type": "string"
+ }
+}Input schema / properties / entity / requiredAdded value: +[
+ "namespace",
+ "ids"
+]Input schema / properties / entity / typeAdded value: +"object"get_timeseries7 fields changedInput schema / $defsRemoved value: -{
- "AgentEntity": {
- "description": "The agent-plane entity shape returned by resolve_entity and consumed by\nget_snapshot / get_timeseries. Extra keys from a resolve result (label,\nconfidence) are accepted and ignored - only namespace + ids are sent on.",
- "properties": {
- "ids": {
- "additionalProperties": true,
- "title": "Ids",
- "type": "object"
- },
- "namespace": {
- "title": "Namespace",
- "type": "string"
- }
- },
- "required": [
- "namespace",
- "ids"
- ],
- "title": "AgentEntity",
- "type": "object"
- }
-}Input schema / properties / entity / $refRemoved value: -"#/$defs/AgentEntity"Input schema / properties / entity / additionalPropertiesAdded value: +trueInput schema / properties / entity / descriptionAdded value: +"Entity dict from resolve_entity ({namespace, ids}). Extra keys are ignored."Input schema / properties / entity / propertiesAdded value: +{
+ "ids": {
+ "additionalProperties": true,
+ "description": "Identifier map from resolve_entity.",
+ "type": "object"
+ },
+ "namespace": {
+ "description": "Entity namespace from resolve_entity.",
+ "type": "string"
+ }
+}Input schema / properties / entity / requiredAdded value: +[
+ "namespace",
+ "ids"
+]Input schema / properties / entity / typeAdded value: +"object"call_endpoint2 fields changedInput schema / properties / fields / descriptionPrevious value: -"Optional projection of keys to keep on each record. Dotted paths (geo.city) walk nested objects. meta.shaped reports fields_applied and fields_unmatched. Omit to keep every key."New value: +"Optional projection of keys to keep on each record of the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). Keys beside that list such as total and count stay. If a field names a key of data itself, or of a payload without data, that object is projected instead; an object data without such a list is otherwise kept whole. Dotted paths (geo.city) walk nested objects. If no field matches, nothing is removed. meta.shaped reports fields_applied, fields_unmatched and records_path. Omit to keep every key."Input schema / properties / limit / descriptionPrevious value: -"Bounds ONLY the top-level list: the envelope data list (or a bare top-level array). Nested lists inside records are never truncated; meta.shaped reports whether the limit applied."New value: +"Bounds ONLY the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). No such list, or several, means the limit does not apply. Keys beside the list such as total and count are not rewritten, and lists nested inside records are never truncated. meta.shaped reports limit_applied and records_path."fetch_data2 fields changedInput schema / properties / fields / descriptionPrevious value: -"Optional projection of keys to keep on each record. Dotted paths (geo.city) walk nested objects. meta.shaped reports fields_applied and fields_unmatched. Omit to keep every key."New value: +"Optional projection of keys to keep on each record of the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). Keys beside that list such as total and count stay. If a field names a key of data itself, or of a payload without data, that object is projected instead; an object data without such a list is otherwise kept whole. Dotted paths (geo.city) walk nested objects. If no field matches, nothing is removed. meta.shaped reports fields_applied, fields_unmatched and records_path. Omit to keep every key."Input schema / properties / limit / descriptionPrevious value: -"Bounds ONLY the top-level list: the envelope data list (or a bare top-level array). Nested lists inside records are never truncated; meta.shaped reports whether the limit applied."New value: +"Bounds ONLY the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). No such list, or several, means the limit does not apply. Keys beside the list such as total and count are not rewritten, and lists nested inside records are never truncated. meta.shaped reports limit_applied and records_path."call_endpoint1 field changedInput schema / properties / body / anyOfPrevious value: -[
- {
- "additionalProperties": true,
- "type": "object"
- },
- {
- "items": {},
- "type": "array"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ {
+ "items": {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+]fetch_data1 field changedInput schema / properties / body / anyOfPrevious value: -[
- {
- "additionalProperties": true,
- "type": "object"
- },
- {
- "items": {},
- "type": "array"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ {
+ "items": {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+]search_endpoints1 field changedInput schema / properties / source / descriptionPrevious value: -"Optional source-family filter as listed by list_sources (sugra_finance, fred, ...). An unknown value returns error unknown_source with known_sources."New value: +"Optional source-family filter as listed by list_sources (macro, markets, ...). An unknown value returns error unknown_source with known_sources."sugra_entity_lookup1 field changedInput schema / properties / include / descriptionPrevious value: -"Optional fuller slices to add, e.g. ownership, adverse_media, profile, screening. Omit for the compact default."New value: +"Optional fuller slices to add, e.g. ownership, adverse_media. Omit for the compact default. profile and screening are already in the compact core and are not extra slices."call_endpoint2 fields changedInput schema / properties / fields / descriptionAdded value: +"Optional projection of keys to keep on each record. Dotted paths (geo.city) walk nested objects. meta.shaped reports fields_applied and fields_unmatched. Omit to keep every key."Input schema / properties / include_raw / descriptionAdded value: +"If true, attach the original unshaped payload under raw when it fits the size cap; otherwise meta.raw_omitted explains why. Default false."describe_endpoint1 field changedInput schema / properties / operation_id / descriptionAdded value: +"Catalog operation_id from search_endpoints (or from list_toolsets drill-down). Unknown ids return error unknown_operation_id."fetch_data3 fields changedInput schema / properties / fields / descriptionAdded value: +"Optional projection of keys to keep on each record. Dotted paths (geo.city) walk nested objects. meta.shaped reports fields_applied and fields_unmatched. Omit to keep every key."Input schema / properties / include_raw / descriptionAdded value: +"If true, attach the original unshaped payload under raw when it fits the size cap; otherwise meta.raw_omitted explains why. Default false."Input schema / properties / query / descriptionAdded value: +"Natural-language request for data (examples: 'US CPI', 'Bitcoin price', 'latest news'). The tool picks the top catalog match and calls it. If required params are missing it returns needs_params instead of guessing."search_endpoints4 fields changedInput schema / properties / limit / descriptionAdded value: +"Maximum ranked hits to return. Default 10. Does not call the Sugra API; this only bounds the catalog search list."Input schema / properties / query / descriptionAdded value: +"Natural-language search over the bundled catalog. Name the instrument, series, place, or task (examples: 'US CPI', 'AAPL quote', 'North Sea AIS'). Returns ranked operation_id hits with required_parameters. Then call describe_endpoint on a hit before call_endpoint."Input schema / properties / source / descriptionAdded value: +"Optional source-family filter as listed by list_sources (sugra_finance, fred, ...). An unknown value returns error unknown_source with known_sources."Input schema / properties / toolset / descriptionAdded value: +"Optional catalog group filter (markets, macro, news, network, ...). Call list_toolsets for the live names. An unknown value returns error unknown_toolset with known_toolsets rather than an empty hit list."sugra_entity_lookup3 fields changedInput schema / properties / anchor / descriptionAdded value: +"Identifier type: lei (GLEIF) or vat (EU VIES)."Input schema / properties / include / descriptionAdded value: +"Optional fuller slices to add, e.g. ownership, adverse_media, profile, screening. Omit for the compact default."Input schema / properties / value / descriptionAdded value: +"The identifier value: 20-character LEI or the VAT number."sugra_entity_screen4 fields changedInput schema / properties / country / descriptionAdded value: +"Optional ISO 3166-1 alpha-2 country to narrow the match."Input schema / properties / dob / descriptionAdded value: +"Optional date of birth for a person, YYYY-MM-DD."Input schema / properties / name / descriptionAdded value: +"Person or organization name to screen (required)."Input schema / properties / nationality / descriptionAdded value: +"Optional nationality to narrow the match."get_timeseries1 field changedInput schema / properties / metric / enumPrevious value: -[
- "price",
- "macro_series",
- "etf_flows"
-]New value: +[
+ "price",
+ "macro_series",
+ "etf_flows",
+ "etf_monthly_flows"
+]Live data gateway for AI — 3,300+ tools across 750+ sources, with citations
Live web access for agents: scrape, SERP search, crawl/map, 100+ collectors, datasets, proxies.
Discover, inspect and run 63,000+ agent tools from one balance. Pay per call, no subscriptions.
Verified, pay-per-use API tools for AI agents through one authenticated connection.
Add one secure layer between your agents and this server.
