Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.
Scored across 11 tools
Most tools have distinct roles: catalog discovery (search_endpoints, describe_endpoint), execution (call_endpoint, fetch_data), entity resolution (resolve_entity, sugra_entity_lookup), and data retrieval (get_snapshot, get_timeseries). fetch_data conceptually overlaps with search+call but is explicitly positioned as a convenience, and the two compliance tools are separated by identifier-based vs name-based screening. Minor ambiguity remains between get_snapshot and get_timeseries, but the descriptions clarify snapshot-vs-series.
All tool names use snake_case and mostly follow a verb_noun pattern (search_endpoints, describe_endpoint, call_endpoint, list_sources, list_toolsets, resolve_entity). The get_snapshot/get_timeseries pair and the sugra_entity_* prefix deviate slightly from the dominant pattern, and fetch_data uses a vaguer verb, but there is no mixing of casing or wildly inconsistent conventions.
11 tools is well-scoped for a data API gateway. The set covers discovery, description, direct calling, natural-language fetch, composed snapshots, timeseries, entity resolution, and compliance screening—each tool earns its place without feeling redundant or filler.
Core workflows are covered end-to-end: search/describe/call with a convenience shortcut, entity resolution feeding snapshots and timeseries, and a separate compliance path. Minor gaps include no explicit way to enumerate snapshot recipes or list available namespaces, but agents can work around these via list_toolsets/search_endpoints and the tool descriptions.
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). 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. | |
| 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. | |
| 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 |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds rich context beyond the annotations: duration_class behaviors, cold-upstream 15s+ latency, gateway timeout risk, batching/concurrency policy, per-item credit billing for bulk endpoints, structured error shape, and the 'upstream_timeout retry warms caches' tactic. This is far more than 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?
Front-loads the core purpose, then organizes hints/behavior into a compact three-sentence paragraph. Slightly dense but every sentence carries operational value; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an endpoint-invocation tool with an output schema present and 83% param coverage, the description supplies the missing operational context (latency classes, retry strategy, billing, error structure) that an agent needs to call correctly. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, so the schema already documents each parameter well (body, limit, fields, params, include_raw). The description adds no per-parameter detail beyond what the schema states. Baseline 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?
States a specific verb and resource: 'Call a Sugra API endpoint by operation_id from the bundled catalog.' The operation_id-keyed invocation and the catalog scoping clearly distinguish it from siblings like describe_endpoint, search_endpoints, or fetch_data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent to describe_endpoint to plan calls (agent_hints, duration_class, max_concurrency, request_body_schema), which is strong when-to-use guidance. It does not state when NOT to use this tool or name a full alternative execution path, but the routing to the sibling is clear.
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.
Examples:
fetch_data("US CPI inflation", params={"series_id": "CPIAUCSL"})
→ calls /api/v1/fred/series/CPIAUCSL, returns observations.
fetch_data("Bitcoin price", params={"coin_id": "bitcoin"})
→ calls /api/v1/crypto/bitcoin/price.
fetch_data("Latest financial news")
→ news_latest has no required params, returns latest news directly.
| 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). 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. | |
| 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?
The 'Behavior' section discloses the three-step internal flow (search → call → retry) including the needs_params fallback, which goes well beyond the annotations' readOnly/idempotent/openWorld hints. It doesn't mention rate limits or the raw/limit/fields shaping meta-keys, but the schema covers those. Annotations already declare safety/idempotency, so a 4 is appropriate.
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 one-sentence purpose, then behavior steps, then examples. Slightly verbose in prose but every section earns its place and the structure (purpose/behavior/examples) is easy to scan.
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 exists, so return-shape description is not required, and the needs_params retry path is well covered. For a 6-param meta-tool with auto-selection, the description supplies the workflow context an agent needs 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 coverage is 100%, so the baseline is 3; the description additionally illustrates params usage with three concrete examples that disambiguate how query+params interact with the auto-selected endpoint, adding real value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb+resource ('find the best Sugra endpoint for the query and call it') and explicitly positions itself against siblings (search_endpoints + call_endpoint + describe_endpoint) by describing itself as a one-step shortcut for natural-language queries.
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 a direct when-to-use ('for most natural-language queries this tool is enough') and points to the alternative sibling chain when explicit control is needed. The multi-step fallback path is named explicitly.
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).
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?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral details: billing cost from quota, the meaning of status 'partial', the trustworthiness of present components, and the freshness block semantics. This goes beyond annotations without contradicting them, though it doesn't cover error handling or edge cases like unknown recipes.
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 dense but well-organized: purpose first, then behavior, then args. Each sentence carries information—recipe list, billing, partial status, freshness, and entity format. No fluff or repetition; it earns 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?
For a complex composed tool with nested objects and an output schema, the description covers all key aspects: how to specify the recipe, how to construct the entity, what the response signals mean, and cost implications. The existence of an output schema means the description need not detail the envelope structure. 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?
Schema coverage is 50%; the recipe parameter has no schema description, but the description lists the fixed manifest names. Entity is described in both schema and description, with the description adding 'Extra keys are ignored' and clarifying it comes from resolve_entity. The description adds meaningful context for recipe and entity format, compensating for the schema 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?
Description states a specific verb (composes), a clear resource (current view of an entity via a named recipe), and enumerates the fixed recipe list. It distinguishes itself from sibling tools like get_timeseries and call_endpoint by emphasizing the composed nature and the server-side manifest. The scope is unambiguous.
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?
Description explains when the tool is appropriate (composed snapshots vs. direct calls) and covers cost implications (fixed 1-2 units from daily quota). It doesn't explicitly name alternatives or say 'use this when...' but the fixed recipe list and billing context imply its role among siblings. Lacks explicit exclusion guidance but provides strong contextual cues.
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.
get_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"
+]call_endpoint1 field changedInput schema / properties / limit / descriptionAdded 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."fetch_data1 field changedInput schema / properties / limit / descriptionAdded 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."call_endpoint2 fields changedInput schema / properties / body / anyOfPrevious value: -[
- {
- "additionalProperties": true,
- "type": "object"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ {
+ "items": {},
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / body / descriptionPrevious value: -"JSON request body for a POST operation, matching the request_body_schema returned by describe_endpoint(operation_id). Omit for GET operations."New value: +"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."fetch_data2 fields changedInput schema / properties / body / anyOfPrevious value: -[
- {
- "additionalProperties": true,
- "type": "object"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ {
+ "items": {},
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / body / descriptionPrevious value: -"JSON body for an auto-selected POST operation; the tool returns the request_body_schema to fill when the match needs one."New value: +"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."call_endpoint2 fields changedInput schema / properties / body / descriptionAdded value: +"JSON request body for a POST operation, matching the request_body_schema returned by describe_endpoint(operation_id). Omit for GET operations."Input schema / properties / params / descriptionAdded 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."fetch_data2 fields changedInput schema / properties / body / descriptionAdded value: +"JSON body for an auto-selected POST operation; the tool returns the request_body_schema to fill when the match needs one."Input schema / properties / params / descriptionAdded value: +"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."get_snapshot5 fields changedInput schema / $defsAdded 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 / $refAdded value: +"#/$defs/AgentEntity"Input schema / properties / entity / additionalPropertiesRemoved value: -trueInput schema / properties / entity / titleRemoved value: -"Entity"Input schema / properties / entity / typeRemoved value: -"object"get_timeseries6 fields changedInput schema / $defsAdded 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 / $refAdded value: +"#/$defs/AgentEntity"Input schema / properties / entity / additionalPropertiesRemoved value: -trueInput schema / properties / entity / titleRemoved value: -"Entity"Input schema / properties / entity / typeRemoved value: -"object"Input schema / properties / metric / enumAdded value: +[
+ "price",
+ "macro_series",
+ "etf_flows"
+]sugra_entity_lookup1 field changedInput schema / properties / anchor / enumAdded value: +[
+ "lei",
+ "vat"
+]call_endpointdescribe_endpointfetch_dataget_snapshotget_timeserieslist_sourceslist_toolsetsresolve_entitysearch_endpointssugra_entity_lookupsugra_entity_screenLive data gateway for AI — 3,300+ tools across 750+ sources, with citations
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.
Real-world data for agents: air quality, geocoding, quakes, holidays, web search
Add one secure layer between your agents and this server.