Sugra API MCP

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial extra behavior: duration classes with typical latencies, cold-upstream timeouts, concurrency limits, per-body-item billing, the structured error shape {error, reason, status_code, elapsed_ms, retry_hint}, and the cache-warming retry insight. This is exactly the kind of context annotations cannot carry.

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

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

Purpose is front-loaded in the first sentence, followed by high-density operational guidance. The paragraph runs long and packs several distinct facts (durations, concurrency, billing, errors, retry), but almost every sentence carries unique value.

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

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

With an output schema present, return values need not be explained, and the description still adds the error shape and retry guidance. For a broad dispatch tool over an external catalog, this is nearly complete; it could add explicit routing versus sibling data tools but covers the essentials.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantic meaning beyond the schema: bulk endpoints bill 1 request credit per body item, and failures return a defined error envelope that ties to retry behavior. It also reinforces the describe_endpoint dependency for params rather than restating field types.

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

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

The description opens with a specific verb and resource: 'Call a Sugra API endpoint by operation_id from the bundled catalog.' This clearly identifies the action and the catalog-scoped identifier. It doesn't explicitly distinguish itself from siblings like fetch_data or get_timeseries, but the operation_id/catalog framing is distinctive enough.

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

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

It gives concrete context: plan calls with describe_endpoint's agent_hints, keep parallel calls within max_concurrency, prefer small batches, and retry once after upstream_timeout. It doesn't state explicit exclusions against sibling tools like fetch_data or get_snapshot, but the planning guidance is actionable.

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

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.

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false), yet the description adds substantial behavior beyond them: top-match-wins selection, the needs_params retry contract, the unknown_parameters error, the country-param auto-injection rule, and the fact that only the top match runs. This is genuinely useful operational detail not derivable from the annotations.

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

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

Front-loaded with the core purpose and alternative routing, then structured as numbered Behavior steps and Examples. It is longer than strictly necessary (three examples plus a trailing counter-example), but every section is load-bearing rather than filler.

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

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

With an output schema present and full annotation coverage, the description need not explain return values; instead it supplies exactly the missing pieces — selection behavior, error/retry contracts, and alternative routing. An agent has everything needed to call this correctly on the first try.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by explaining the retry flow for `params` (returns required_parameters and examples), the `query` natural-language contract, and the unknown_parameters failure mode. It does not restate the schema's extensive limit/fields semantics, which the schema already carries.

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

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

States a specific verb+resource ('fetch data') and immediately distinguishes itself from siblings: it 'Combines search_endpoints + call_endpoint into a single round trip.' The agent can tell it apart from search_endpoints, describe_endpoint, and call_endpoint without opening any schema.

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

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

Explicit when-to-use ('when you want data without manually picking an operation_id'), when the alternative is warranted ('the full search_endpoints + describe_endpoint + call_endpoint dance is still available when you need explicit control'), and a concrete fallback for a specific case ('For one coin's price, name the operation: call_endpoint(...)'). Nothing is left to inference.

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

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.

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.

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.

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.

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.