Sugra API
Server Details
Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.3/5 across 11 of 11 tools scored. Lowest: 3.6/5.
Each tool has a clearly distinct purpose. Tools like call_endpoint, describe_endpoint, fetch_data, and search_endpoints handle different stages of endpoint interaction. Compliance tools (sugra_entity_lookup, sugra_entity_screen) are separate from market-data tools (get_snapshot, get_timeseries). There is no ambiguity or overlap.
All tool names follow a consistent snake_case verb_noun pattern. Compliance tools are prefixed with 'sugra_' for grouping. No mixing of conventions (e.g., camelCase). The naming is predictable and intuitive.
11 tools is a well-scoped set for a financial data API. It covers endpoint discovery, data fetching, entity resolution, and compliance screening without being excessive. Each tool earns its place.
The tool surface covers all necessary operations: searching, describing, calling endpoints, fetching composed data, resolving entities, and compliance lookups. There are no obvious gaps for the server's purpose of providing access to a catalog of endpoints and composed insights.
Available Tools
11 toolscall_endpointARead-onlyIdempotentInspect
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 | ||
| limit | No | ||
| fields | No | ||
| params | No | ||
| include_raw | No | ||
| operation_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations. It explains response time variability, concurrency constraints, billing implications, error structure, and retry behavior. The annotations (readOnlyHint, idempotentHint) are consistent with the description, and no contradiction is present.
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, starting with the core purpose and then providing detailed behavioral notes. It is packed with useful information but could be slightly more concise. Every sentence earns its place, though the length is justified by the content.
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 covers usage patterns, performance, and error handling well. However, it fails to describe the parameters or the output (though output schema exists, so the latter is less critical). Given the complexity of the tool, the omission of parameter semantics makes it incomplete.
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?
Despite low schema coverage (0%), the description does not explain the individual parameters (body, limit, fields, params, include_raw). It mentions operation_id implicitly but provides no details on how to use the other parameters. The description fails to compensate 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?
The description clearly states it calls a Sugra API endpoint by operation_id. It is specific about the resource and how it is identified. However, it does not explicitly differentiate from sibling tools like describe_endpoint or search_endpoints, which lowers the score slightly.
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 excellent usage guidance: it tells when to use this tool, references describe_endpoint for planning, explains duration classes (fast, slow, heavy) with typical response times, concurrency limits, billing for bulk endpoints, and error handling with retry advice. It covers when-not-to-use implicitly through performance warnings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
describe_endpointARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| operation_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and idempotent. The description adds that it includes agent_hints (duration_class, max_concurrency, bulk billing) and request_body_schema for POST endpoints, going beyond 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 two sentences, front-loaded with the purpose, and every sentence adds value without fluff.
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 simplicity (one parameter, has output schema, annotations cover safety), the description completely covers what the tool does, what it returns, and how to use it.
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 only parameter, operation_id, is not described in the schema (0% coverage), but the description implies its purpose by saying 'by operation_id'. This adds sufficient meaning for a single obvious parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Describe one Sugra API endpoint by operation_id', using a specific verb and resource. It distinguishes from siblings like call_endpoint and search_endpoints.
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 explains when to use this tool: before calling an endpoint to get agent_hints and request_body_schema. It does not explicitly mention alternatives, but usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
fetch_dataARead-onlyIdempotentInspect
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
paramsdict 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 | ||
| limit | No | ||
| query | Yes | ||
| fields | No | ||
| params | No | ||
| include_raw | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details the tool's internal steps (search catalog, check required params, call endpoint or return missing params). This adds substantial context beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), disclosing conditional behavior and error recovery.
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-line purpose, then bulleted steps, followed by concrete examples. Every sentence adds value, and the format is easy to scan. No fluff or repetition.
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 covers the main workflow and behavioral nuances but fails to document all six parameters (0% schema coverage). Although an output schema exists (not shown), the missing parameter explanations reduce completeness for a tool with this many inputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should compensate by explaining each parameter. It only mentions 'query' and 'params' in examples and omits body, limit, fields, and include_raw. While examples illustrate usage, the lack of explicit parameter meanings leaves ambiguity.
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 the tool's purpose as a one-step fetch that finds and calls the best Sugra endpoint. It distinguishes itself from sibling tools like search_endpoints and call_endpoint by combining them into a single round trip, and references the manual dance for explicit control.
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 advises when to use this tool ('when you want data without manually picking an operation_id') and when not to ('the full search_endpoints + describe_endpoint + call_endpoint dance is still available when you need explicit control'). This provides clear usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_snapshotARead-onlyIdempotentInspect
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 | ||
| recipe | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds value by detailing billing (1-2 units from daily quota), freshness block, and that status 'partial' means optional component missing but present data is trustworthy. No contradiction with 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 concise yet informative, with a clear structure: purpose, behavior notes, and argument details. Every sentence adds value without redundancy.
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 presence of an output schema and comprehensive annotations, the description covers all necessary aspects: what it does, how to use it, behavioral nuances (cost, partial status), and parameter semantics. It is complete for an agent to invoke 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 provides no descriptions (0% coverage). The description compensates by explaining that 'recipe' is from a fixed manifest and 'entity' is a dict from resolve_entity, adding meaning beyond the schema for both parameters.
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 'Composed current view of an entity via a named recipe' and lists specific recipe names, making the tool's function unambiguous. It distinguishes from siblings like resolve_entity and get_timeseries by focusing on precomputed snapshots.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context on when to use (with a recipe and entity dict from resolve_entity), mentions cost implications, and explains the partial status. However, it does not explicitly state when not to use this tool compared to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_timeseriesARead-onlyIdempotentInspect
Bounded timeseries for an entity: price, macro_series, or etf_flows.
Returns points oldest-first with an explicit downsampling flag when the raw series exceeded max_points. etf_flows is filing-cadence (one point per SEC filing refresh), NOT per calendar day, so even a wide window yields a handful of points. Times are UTC. Costs 1 unit per call.
Args: metric: One of price / macro_series / etf_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 | ||
| metric | Yes | ||
| max_points | No | ||
| granularity | No | 1d |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds: oldest-first ordering, downsampling flag, filing-cadence for etf_flows, UTC times, and cost per call. No contradictions with 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?
Every sentence is valuable: a one-line purpose, followed by concise behavioral notes and parameter descriptions. Front-loaded structure with no redundant text.
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 complexity (4 params, nested object, output schema exists), the description covers purpose, parameters, behavioral nuances, and links to resolve_entity. The output schema handles return formatting, so no gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description compensates fully by detailing each parameter: metric options, entity dict structure, granularity default, and max_points cap. This adds critical meaning beyond the bare 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?
The description clearly states the tool returns bounded timeseries for specific metrics (price, macro_series, etf_flows), distinguishing it from sibling tools like get_snapshot or fetch_data. The verb 'get' and resource 'timeseries' are precise.
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 context for when to use (e.g., etf_flows filing-cadence nuance) and implies the entity should come from resolve_entity. However, it lacks explicit direction on when not to use this tool versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_sourcesARead-onlyIdempotentInspect
List endpoint source families derived from catalog metadata.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, clearly establishing the tool's safety profile. The description adds behavioral context by noting the data is 'derived from catalog metadata,' indicating it is not live data. This adds value beyond 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 a single, clear sentence with no superfluous words. It is front-loaded and every word earns its place, achieving excellent conciseness.
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 has no parameters, clear annotations, and an output schema exists, the description provides adequate context. It could be improved by briefly defining what constitutes a 'source family,' but overall it is sufficient 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 no parameters, so schema coverage is 100% trivially. The description does not need to add parameter-level information. According to the baseline rule for zero parameters, a score of 4 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 clearly states the tool lists 'endpoint source families derived from catalog metadata,' identifying the specific resource and operation. It distinguishes from sibling tools like list_toolsets by targeting a different resource type. However, the term 'source families' may be ambiguous without further context, preventing a top score.
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 implicitly indicates when to use the tool (to obtain a list of source families), but it provides no explicit guidance on when not to use it or how it compares to alternatives like search_endpoints or list_toolsets. The usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_toolsetsARead-onlyIdempotentInspect
List endpoint groups available in the bundled catalog.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context about 'bundled catalog,' enhancing transparency beyond annotations without contradiction.
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 a single, efficient sentence with no extraneous words, front-loading the core action and scope.
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 simple nature (no parameters, output schema present, comprehensive annotations), the description fully covers what the tool does and from where.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the description does not need to explain them. The absence of parameters is clear, and no additional semantics are required.
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 the verb (list) and resource (endpoint groups/toolsets), and distinguishes from sibling tools which focus on endpoints or data retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives; usage is implied through the purpose, but no when-not or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
resolve_entityARead-onlyIdempotentInspect
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. 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 |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds critical behavioral context: 'NEVER silently picks one' on ambiguity and the type_hint narrowing mechanism, which goes beyond 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 the main purpose and each sentence adds value. It is moderately sized without unnecessary words, though it could be slightly more concise.
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 complexity of entity resolution and ambiguity handling, the description covers the key points: input types, output form, collision behavior, and linkages to other tools. The presence of an output schema reduces the need to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully explains both parameters: query as free-form text with examples, and type_hint as an optional namespace hint. This adds meaning beyond the schema, though further detail on type_hint values could be useful.
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 the tool's purpose with a specific verb-resource pair: 'Resolve free text to a canonical market or macro entity.' It explicitly names the output format and distinguishes from sibling tools like sugra_entity_lookup and sugra_entity_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 provides clear context on when to use this tool vs alternatives (compliance vs market-data entities) and explains the ambiguous collision behavior with type_hint. It stops short of explicitly stating 'do not use for X' but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_endpointsARead-onlyIdempotentInspect
Search the bundled Sugra endpoint catalog by natural-language query.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| source | No | ||
| toolset | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds the key behavioral detail that the query is in natural language, which is a significant trait beyond the annotations. No contradictions; the description is consistent with 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 a single sentence of 10 words, extremely concise with no wasted words. It front-loads the action ('search') and includes the essential elements: verb, resource, and method.
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 tool with 4 parameters and 10 sibling tools, the description is minimally adequate. It covers the core purpose and the main input (natural-language query), but lacks details on optional parameters and guidance on when to use this tool over other search-like siblings. The presence of an output schema mitigates the need for return value documentation, but the parameter gaps reduce completeness.
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 4 parameters with 0% description coverage in the schema. The description only clarifies that the 'query' parameter is a natural-language query, but provides no explanation for 'limit', 'source', or 'toolset'. This is insufficient for an agent to use the tool correctly without additional context.
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 the specific verb 'search' and identifies the resource as 'the bundled Sugra endpoint catalog' with the method 'by natural-language query'. This clearly distinguishes it from sibling tools like call_endpoint, describe_endpoint, fetch_data, etc., which perform different actions.
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 does not provide any guidance on when to use this tool versus alternatives. While it states the action (search by natural language), it does not mention scenarios where other tools (e.g., sugra_entity_lookup, describe_endpoint) would be more appropriate, nor does it specify any prerequisites or warnings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sugra_entity_lookupARead-onlyIdempotentInspect
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 | ||
| anchor | Yes | ||
| include | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable context: compact default output to protect context budget, output structure, error handling returns dict not raise, and disclaimers about screening and PEP/adverse-media being non-comprehensive. 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 front-loaded with a clear first sentence, then logically structured: identifier details, disclaimer, output format, error handling, and parameter args. Every sentence adds value; no redundancy. Concise given the complexity.
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 with 3 parameters (2 required), an output schema exists, and the description thoroughly covers output structure, optional details, error behavior, and usage examples. The agent has all necessary context to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. It explains anchor types with registries, value format with examples, and include parameter usage with examples. This provides complete parameter semantics 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?
The description clearly states the tool resolves an entity by identifier and returns a composed KYB envelope. It specifies identifier types (LEI, VAT) and output components. Although it doesn't explicitly differentiate from siblings like 'resolve_entity,' the purpose is highly specific and 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?
The description explains when to use the tool (lookup by LEI or VAT), notes that screening is a signal not a compliance determination, and describes error handling. It does not explicitly state when not to use it or compare to alternatives, but the context is clear enough for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sugra_entity_screenARead-onlyIdempotentInspect
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 | ||
| name | Yes | ||
| country | No | ||
| nationality | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral context: the output is compact to protect agent context, the verdict values are 'clear', 'review', or 'hit', and it notes that PEP/adverse-media coverage is non-comprehensive. This extends beyond what annotations provide.
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 the core purpose and then provides structured details. It is reasonably concise, covering essentials without verbosity. However, the paragraph on the disclaimer and output format could be slightly tighter.
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 presence of an output schema (not shown), the description adequately explains the compact response format and the meaning of the status field. It covers the main functionality and limitations. Lacking explicit error handling or rate limit info, but still complete enough for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It provides an Args block explaining all four parameters: name (required), country (optional ISO 3166-1 alpha-2), dob (optional YYYY-MM-DD), and nationality (optional). This adds meaning beyond the schema, though it lacks example values or further constraints.
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 the tool screens a person or organization name against the Sugra sanctions corpus. It uses specific verbs and resources, and distinguishes itself by noting it returns a screening signal, not a compliance determination. Although it does not explicitly differentiate from the sibling sugra_entity_lookup, the purpose is unmistakable.
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 context on when to use the tool (for quick screening) and mentions an alternative: using the Sugra API directly when the full envelope is needed. However, it does not explicitly exclude use cases or compare with the sibling sugra_entity_lookup, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!