Skip to main content
Tool invocation is where AI agents execute actual backend operations. After discovering available tools, agents call tools/call with a tool name and arguments, and Grand Central translates that into REST API calls to your banking systems.

​
Invocation request structure

Agents provide the tool name and arguments in a JSON-RPC request: 
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "getAccountBalance",
    "arguments": {
      "accountId": "ACC-789456"
    }
  },
  "id": 2
}

​
Response format

Grand Central returns structured data the agent can parse and reason about: 
{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"accountId\":\"ACC-789456\",\"currentBalance\":15234.50,\"availableCredit\":4765.50,\"currency\":\"USD\"}"
      }
    ]
  },
  "id": 2
}
The response wraps your backend API’s JSON in MCP’s content structure. Agents extract the text field and parse it as JSON to access balance data, then present it to users in natural language: “Your checking account has $15,234.50 available.”

​
Request processing flow

Here’s what happens when an agent invokes a tool: Authentication happens first - subscription key validation plus optional JWT token verification. Rate limiting prevents quota overruns before touching backend systems. Backend API calls use standard REST - GET, POST, PUT, DELETE with JSON payloads mapped from tool arguments. Audit logging runs asynchronously so it doesn’t block responses.

​
Error handling

Tool invocations can fail for multiple reasons - authentication issues, rate limits, validation errors, or backend problems. Grand Central provides structured error responses that agents can parse and handle gracefully:
Cause: Invalid subscription key, expired JWT token, or missing credentials.
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Unauthorized: JWT token expired at 2025-12-04T10:30:00Z"
  },
  "id": 2
}
Agent should: Refresh JWT token if possible, otherwise ask user to re-authenticate. Log the error and alert developers if subscription key issues persist.
Cause: Exceeded quota for the time window (e.g., 100 requests/minute).
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Window: 60

{
  "error": "Rate limit exceeded. 45 seconds until window resets."
}
Agent should: Implement exponential backoff (wait 1s, 2s, 4s between retries), cache results to reduce redundant calls, or inform user about temporary delay. See Rate Limiting for implementation patterns.
Cause: Missing required parameters or invalid parameter types/formats.
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params: accountId must match pattern ^ACC-[0-9]{6}$"
  },
  "id": 2
}
Agent should: Re-construct the request with corrected parameters or ask user for clarification. These errors indicate agent logic issues, not transient failures.
Cause: Backend API returned error (4xx/5xx status codes) or timed out.
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Backend API error: Account not found (404)"
  },
  "id": 2
}
Agent should: Communicate the error to users in plain language (“I couldn’t find that account”) and decide whether to retry (for 5xx errors) or fail immediately (for 4xx errors).

​
Performance optimization

Well-designed agents optimize tool invocations to provide fast, efficient user experiences. Grand Central supports several optimization strategies that work together: Parameter validation happens at the edge before backend calls execute. Grand Central checks required fields, data types, and format patterns (e.g., ^ACC-[0-9]{6}$ for account IDs) using OpenAPI schemas. This catches ~30-40% of potential errors without hitting backend APIs, saving latency and rate limit quota. When an agent submits { "accountId": "12345" } instead of "ACC-123456", it gets an immediate -32602 validation error rather than waiting for the backend to reject it. Response caching improves perceived performance for stable data. Grand Central caches responses from tools that return reference data (currency exchange rates, product catalogs, country lists). When 20 concurrent agents all need the same exchange rate data, only one backend call fires - the other 19 get cached responses in ~5ms instead of ~150ms. Cache TTLs vary by data type (rates: 5min, catalogs: 1hr, compliance lists: 24hr). Agents don’t control caching directly; it’s transparent infrastructure optimization. Parallel invocation speeds up workflows with independent operations. If an agent needs both getCustomer and listTransactions, fire both requests simultaneously. Grand Central’s rate limiting accounts for concurrent requests (burst allowance: 20 req/sec for 2s), so parallelism doesn’t immediately hit quota limits. Just ensure the operations are genuinely independent - don’t parallelize createPayment and getPaymentStatus for the same payment. Automatic retry logic handles transient failures gracefully. Grand Central retries idempotent operations (GET, safe POST operations marked with x-idempotent: true in OpenAPI) on 5xx errors with exponential backoff (1s, 2s, 4s). Agents see either a successful response or a meaningful error after retries exhaust. Non-idempotent operations (payment creation, account updates) fail immediately rather than risking duplicate side effects.

​
Best practices

When building agents that invoke Grand Central tools, follow these patterns for reliability and user satisfaction: Validate inputs before sending requests. Even though Grand Central validates parameters, catching errors in agent code is faster and provides better user feedback. If a user types “get balance for account 12345”, the agent should recognize the missing ACC- prefix and ask for clarification rather than firing a doomed API call. Parse error codes and provide human-readable feedback. Don’t expose raw JSON-RPC errors to end users. When Grand Central returns -32001 Unauthorized, the agent should say “I need you to log in again - your session expired” rather than showing technical error details. Use error codes to trigger specific recovery actions: retry for -32000 (backend errors), refresh auth for -32001, ask user for help with -32602 (validation errors). Implement client-side throttling to stay within rate limits. Track your request rate locally and add small delays (50-100ms) between bursts of requests. Better to proactively throttle than hit 429 errors and deal with exponential backoff delays. If your agent workflow involves 10+ sequential tool calls, consider whether some can be parallelized or combined (batch endpoints). Set realistic timeouts based on expected response times from tool discovery metadata. For fast account queries: 2-3s. For payment creation or complex reports: 5-10s. For async operations that return job IDs: 1-2s for the initial call, then poll status every 3-5s. Don’t use 30s+ timeouts - users perceive slow responses as failures, and you’ll waste quota waiting for requests that already died. Log tool invocations for debugging and analytics. Track which tools agents use most frequently, error rates by tool, and P50/P95 latency. This data helps identify integration issues (“why is getTransactionHistory suddenly slow?”), optimize agent workflows (“we’re calling getCustomer 5 times per conversation - let’s cache it”), and inform backend capacity planning.

​
Next steps

Authentication

Configure API key authentication with optional JWT

Rate limiting

Understand rate limiting and quota management