Tools

How agents discover and invoke tools via the MCP protocol.

Tool Discovery

When an agent starts a conversation, it calls tools/list on each of its assigned skill servers to discover available tools.

Request: tools/list

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "save_csv",
        "description": "Save parsed invoice data as a CSV file to the shared drive",
        "inputSchema": {
          "type": "object",
          "properties": {
            "filename": {
              "type": "string",
              "description": "Output filename without extension"
            },
            "rows": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "date": { "type": "string" },
                  "amount": { "type": "number" },
                  "vendor": { "type": "string" }
                }
              }
            }
          },
          "required": ["filename", "rows"]
        }
      }
    ]
  }
}

Field	Type	Description
name*	string	Unique tool identifier. Used by the agent to reference this tool.
description*	string	Human-readable description. The LLM uses this to decide when to call the tool.
inputSchema*	JSON Schema	JSON Schema defining the tool's input parameters.

Write detailed descriptions. The LLM decides which tool to call based on the description and parameter names. Be specific about what the tool does and when to use it.

Tool Invocation

When the agent decides to call a tool, Agent Platform sends a tools/call request to your MCP server.

Request: tools/call

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "save_csv",
    "arguments": {
      "filename": "invoice-2024-001",
      "rows": [
        { "date": "2024-01-15", "amount": 1250.00, "vendor": "Acme Corp" },
        { "date": "2024-01-16", "amount": 890.50, "vendor": "Widget Inc" }
      ]
    }
  }
}

Success response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "CSV saved to /shared/invoices/invoice-2024-001.csv (2 rows)"
      }
    ]
  }
}

Error response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Failed to save CSV: permission denied on /shared/invoices/"
      }
    ],
    "isError": true
  }
}

Tool errors are returned in the result with isError: true, not as JSON-RPC errors. This allows the agent to see the error message and decide how to recover.

Protected MCP Servers

MCP servers can require OAuth without storing static credentials in skill definitions.

If an MCP server responds to an unauthenticated initialize request with WWW-Authenticate and OAuth Protected Resource Metadata, Agent Platform requests a scoped token and retries the MCP session. The token request includes the MCP server resource URL so the server can reject tokens issued for any other resource.

Required challenge shape

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/mcp/.well-known/oauth-protected-resource", error="invalid_token"

Do not authorize MCP calls from caller-supplied org or tenant headers. Derive routing context from validated token claims, then synthesize any trusted internal headers after validation.

Approval Gate

Tools that modify data can require human approval before execution. The agent pauses and waits for a human to approve or reject the tool call.

Whether a tool requires approval is configured per-skill in Agent Platform. When auto_approve is disabled, every tool call from that skill goes through the approval gate:

Agent decides to call a tool
Platform creates a confirmation request with the tool name and arguments
A human reviewer approves or rejects via the dashboard
If approved, the tool call proceeds to your MCP server
If rejected, the agent is told the tool call was denied and can try something else

Approval gates have a configurable timeout (default: 5 minutes). If no human responds, the tool call is automatically rejected.