Skip to main content
Glama
Sugra-Systems

Sugra API MCP

Official
by Sugra-Systems
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

call_endpoint

Read-onlyIdempotent

Execute a Sugra API endpoint by operation ID, passing query params and a JSON body to get structured response data from the bundled catalog.

Instructions

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
bodyNoJSON 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.
limitNoBounds 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.
fieldsNoOptional 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.
paramsNoQuery 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_rawNoIf true, attach the original unshaped payload under raw when it fits the size cap; otherwise meta.raw_omitted explains why. Default false.
operation_idYes

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.11.0
    • addedInput schema / properties / fields / description
      Added 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."
    • addedInput schema / properties / include_raw / description
      Added value: +"If true, attach the original unshaped payload under raw when it fits the size cap; otherwise meta.raw_omitted explains why. Default false."
    • addedInput schema / properties / limit / description
      Added 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."
  2. Changed2 schema fields changedv0.9.1
    • changedInput schema / properties / body / anyOf
      Previous value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  {
+    "items": {},
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]
    • changedInput schema / properties / body / description
      Previous 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."
  3. First observedv0.8.2

TDQS

A3.9/5.0
Behavior3/5

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

The description adds valuable behavioral context such as response times per duration_class, bulk billing, and error structures, which exceeds the annotations. Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description enriches with performance and error details but doesn't constrain further.

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

Conciseness4/5

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

The description is well-structured, starting with the core purpose and then providing operational guidance in a logical flow. It is dense with useful information but remains focused; each sentence contributes to understanding performance, billing, and error handling.

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

Completeness4/5

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

Given the tool's complexity with six parameters and nuance like duration_class and bulk billing, the description covers performance expectations, error handling, and retry strategy. However, it doesn't elaborate on the output schema, but since an output schema exists, additional explanation is not necessary.

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

Parameters3/5

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

Schema coverage is 83%, with detailed descriptions in the schema for body, limit, fields, and params. The description does not add significant new meaning beyond what the schema already provides, but it does mention the operation_id and its role in retrieving schemas. Baseline 3 is appropriate given the high schema coverage.

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

Purpose5/5

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

The description clearly states the tool calls a Sugra API endpoint by operation_id from a bundled catalog, which is specific and distinguishes it from siblings like search_endpoints or describe_endpoint. The verb 'call' and resource 'endpoint' are precise.

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

Usage Guidelines4/5

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

It provides detailed guidance on when to use this tool, including how to plan calls using describe_endpoint's agent_hints and the importance of referring to describe_endpoint for parameters. It doesn't explicitly state when NOT to use it, but the guidance is clear enough about preconditions.

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

Deploy Server

Other Tools