> ## Documentation Index
> Fetch the complete documentation index at: https://grandcentral.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool invocation

> How AI agents invoke MCP tools to execute operations

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:

```json theme={"system"}
{
  "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:

```json theme={"system"}
{
  "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:

```mermaid theme={"system"}
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#ffffff',
    'primaryBorderColor': '#295eff',
    'primaryTextColor': '#091c35',
    'lineColor': '#091c35',
    'secondaryColor': '#f3f6f9',
    'tertiaryColor': '#ebf0f5',
    'fontFamily': 'Libre Franklin, sans-serif'
  }
}}%%
sequenceDiagram
    participant Agent
    participant GC as Grand Central
    participant Auth
    participant Backend
    
    Agent->>GC: tools/call request
    GC->>Auth: Validate subscription key + JWT
    Auth-->>GC: Authentication OK
    GC->>GC: Check rate limits
    GC->>Backend: HTTP request to backend API
    Backend-->>GC: JSON response
    GC->>GC: Async audit logging
    GC-->>Agent: MCP response with data
```

**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:

<AccordionGroup>
  <Accordion title="Authentication errors (401)">
    **Cause**: Invalid subscription key, expired JWT token, or missing credentials.

    ```json theme={"system"}
    {
      "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.
  </Accordion>

  <Accordion title="Rate limit errors (429)">
    **Cause**: Exceeded quota for the time window (e.g., 100 requests/minute).

    ```http theme={"system"}
    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](/agentic-ai/mcp-support/capabilities/rate-limiting) for implementation patterns.
  </Accordion>

  <Accordion title="Validation errors (-32602)">
    **Cause**: Missing required parameters or invalid parameter types/formats.

    ```json theme={"system"}
    {
      "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.
  </Accordion>

  <Accordion title="Backend errors (varies)">
    **Cause**: Backend API returned error (4xx/5xx status codes) or timed out.

    ```json theme={"system"}
    {
      "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).
  </Accordion>
</AccordionGroup>

## 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

<CardGroup cols={2}>
  <Card title="Authentication" icon="shield" href="/mcp/capabilities/authentication">
    Configure API key authentication with optional JWT
  </Card>

  <Card title="Rate limiting" icon="gauge" href="/mcp/capabilities/rate-limiting">
    Understand rate limiting and quota management
  </Card>
</CardGroup>