Meta-Tool Specifications

This is the complete technical reference for Toolcog’s API meta-tools. These tools are exposed via the Model Context Protocol (MCP) and enable AI to discover, learn, and execute API operations.

Overview

Tool	Purpose	Behavior
`find_api`	Discover operations	Semantic search, read-only
`learn_api`	Learn interfaces	TypeScript generation, read-only
`call_api`	Execute operations	HTTP requests, may modify state

All tools return the same response structure:

interface ToolResult {
  content: Array<{ type: "text"; text: string }>;
  isError?: boolean;
}

isError: false or undefined indicates success
isError: true indicates an error occurred

find_api

Discovers API operations matching a natural language intent using semantic search.

Parameters

Parameter	Type	Required	Description
`intent`	string	Yes	What you want to accomplish

Input Schema

{
  "type": "object",
  "properties": {
    "intent": {
      "type": "string",
      "description": "The behavior of the API operation you intend to perform"
    }
  },
  "required": ["intent"]
}

Intent Guidelines

The intent should describe behavior, not entities:

Good Intent	Bad Intent
”create a new customer with email and payment info"	"stripe customer"
"list all repositories for a user"	"github repos"
"send a transactional email with template"	"sendgrid email”

Good intents:

Describe what the operation does when called
Include key parameters or capabilities
Are specific enough to narrow results

Bad intents:

Just name entities or services
Are too vague to differentiate operations
Include unnecessary context

Success Response

Returns a markdown-formatted list of matching operations:

Found 3 API operation(s):

- stripe/customers.create — create a new customer with email and payment details
- stripe/customers.update — modify an existing customer's information
- braintree/customers.create — create a customer in the payment vault

Each result includes:

serviceName/operationName — The operation identifier
A phrase describing the match

Results are ranked by semantic similarity. The top 10 matches are returned.

No Results Response

No API operations found matching your intent. Try rephrasing your search.

Error Response

{
  content: [{ type: "text", text: "Missing intent parameter" }],
  isError: true
}

Behavior Notes

Uses text-embedding-3-small for vector embeddings
Searches within the session’s catalog scope
Returns empty result (not error) when no matches found
Case-insensitive matching

learn_api

Retrieves TypeScript type declarations for an operation’s request and response interfaces.

Parameters

Parameter	Type	Required	Default	Description
`operation`	string	Yes	—	Operation identifier
`request`	boolean	No	`true`	Include request types
`response`	boolean	No	`false`	Include response types

Input Schema

{
  "type": "object",
  "properties": {
    "operation": {
      "type": "string",
      "description": "The API operation to learn about (format: serviceName/operationName)"
    },
    "request": {
      "type": "boolean",
      "description": "Include request types",
      "default": true
    },
    "response": {
      "type": "boolean",
      "description": "Include response types",
      "default": false
    }
  },
  "required": ["operation"]
}

Operation Format

Operations must be specified as serviceName/operationName:

github/repos.create
stripe/customers.create
sendgrid/mail.send

Invalid formats return an error.

Success Response

Returns TypeScript type declarations:

interface CreateCustomerRequest {
  email: string;
  name?: string;
  description?: string;
  metadata?: Record<string, string>;
  payment_method?: string;
  address?: Address;
}

interface Address {
  line1: string;
  line2?: string;
  city: string;
  state?: string;
  postal_code: string;
  country: string;
}

The response includes:

Main operation interface
All dependent type definitions (resolved from $ref chains)
Algebraically simplified types (unions reduced, optionals marked)

Reference Resolution

Types are resolved to a depth of 2 indirections. Deep circular references are truncated with inline comments.

Error Responses

Invalid format:

Invalid operation format. Expected: serviceName/operationName

Operation not found:

Operation not found: stripe/invalid.operation

No types available:

No type information available for this operation.

Behavior Notes

Specs are downloaded on-demand from the Hub
Tree-shaking extracts only required schemas
Response types include all possible status codes unless filtered
Scoped to the session’s catalog

call_api

Executes an API operation with the provided arguments.

Parameters

Parameter	Type	Required	Description
`operation`	string	Yes	Operation identifier
`arguments`	object	Yes	Arguments by location

Arguments Structure

interface Arguments {
  path?: Record<string, unknown>; // Path parameters
  query?: Record<string, unknown>; // Query string parameters
  header?: Record<string, unknown>; // Request headers
  body?: unknown; // Request body
  server?: Record<string, unknown>; // Server URL variables
  cookie?: Record<string, unknown>; // Cookie values
}

Input Schema

{
  "type": "object",
  "properties": {
    "operation": {
      "type": "string",
      "description": "The API operation to call (format: serviceName/operationName)"
    },
    "arguments": {
      "type": "object",
      "properties": {
        "path": {
          "type": "object",
          "description": "Path arguments"
        },
        "query": {
          "type": "object",
          "description": "Query arguments"
        },
        "header": {
          "type": "object",
          "description": "Header arguments"
        },
        "body": {
          "description": "Body argument"
        }
      },
      "required": []
    }
  },
  "required": ["operation", "arguments"]
}

Example Call

{
  "operation": "github/repos.create",
  "arguments": {
    "body": {
      "name": "my-new-repo",
      "description": "A repository created via Toolcog",
      "private": true
    }
  }
}

Success Response

Returns the HTTP response:

{
  "status": 201,
  "statusText": "Created",
  "body": {
    "id": 123456789,
    "name": "my-new-repo",
    "full_name": "user/my-new-repo",
    "private": true,
    "html_url": "https://github.com/user/my-new-repo"
  }
}

Response fields:

status — HTTP status code (e.g., 200, 201, 400, 500)
statusText — HTTP status text (e.g., “OK”, “Created”, “Bad Request”)
body — Decoded response body (JSON parsed if applicable)

Error Responses

Missing operation:

Missing "operation" parameter

Missing arguments:

Missing "arguments" parameter

Invalid format:

Invalid operation format. Expected: serviceName/operationName

Operation not found:

Operation not found: stripe/invalid.operation

Authorization required:

When credentials are missing or insufficient, the response includes:

{
  "status": 401,
  "statusText": "Unauthorized",
  "body": {
    "error": "authorization_required",
    "message": "This operation requires authorization",
    "connect_url": "https://toolcog.com/connect?owner={owner}&bridge={bridge}&scope=repo"
  }
}

The connect_url can be provided to the user to authorize the service.

Credential Resolution

Credentials are resolved automatically based on the operation’s security requirements:

Credential Type	Satisfies Schemes
OAuth	`oauth2`, `http:bearer`
API Key	`apiKey`
HTTP Basic	`http:basic`
HTTP Bearer	`http:bearer`

Credentials must match the scheme name declared in the operation’s security requirements.

Behavior Notes

Credentials are retrieved from the user’s encrypted vault
Authorization is transparent—AI doesn’t see credentials
Sets User-Agent: env.USER_AGENT automatically
Authorization failure for one operation doesn’t imply failure for others
Scoped to the session’s catalog and vault

Common Error Handling

All tools follow consistent error patterns:

Parameter Validation

Missing or invalid parameters return immediately with isError: true:

{
  content: [{ type: "text", text: "Error message describing the issue" }],
  isError: true
}

Operation Format

Operations must match serviceName/operationName:

Must contain exactly one /
Both segments must be non-empty
Case-sensitive matching

Session Context

All tools require an active MCP session. Outside a valid session:

Session not found

Exceptions

Unexpected errors are caught and returned as:

{
  content: [{ type: "text", text: error.message }],
  isError: true
}

MCP Protocol Details

Protocol Version

2025-06-18

Tool Annotations

Tool	`readOnlyHint`	`destructiveHint`	`openWorldHint`
`find_api`	`true`	—	`true`
`learn_api`	`true`	—	`true`
`call_api`	—	`true`	`true`

readOnlyHint: true — Tool doesn’t modify state
destructiveHint: true — Tool may modify state
openWorldHint: true — Tool accesses external systems

Message Format

JSON-RPC 2.0 over the configured transport (stdio, SSE, WebSocket).

Best Practices

Discovery First

Always use find_api before claiming an operation doesn’t exist:

1. find_api("create a payment intent")
2. learn_api("stripe/payment_intents.create", request: true)
3. call_api("stripe/payment_intents.create", arguments: {...})

Type Learning

Use learn_api before complex operations:

Understand required vs optional parameters
Learn the expected body structure
Check response types for error handling

Authorization Handling

When call_api returns authorization_required:

Extract the connect_url from the response
Present it to the user as a clickable link
After user authorizes, retry the operation

Error Recovery

Invalid operation? Check find_api results for correct name
Missing parameters? Use learn_api to learn the interface
Authorization failed? Provide the connect URL to the user

Next Steps

API Meta-Tools — Conceptual overview
Semantic Search — How find_api works
Hygienic Execution — How call_api handles auth

MCP Clients

Agent SDKs

Integrations

Technology

Learn

Company

Meta-Tool Specifications

Overview

find_api

Parameters

Input Schema

Intent Guidelines

Success Response

No Results Response

Error Response

Behavior Notes

learn_api

Parameters

Input Schema

Operation Format

Success Response

Reference Resolution

Error Responses

Behavior Notes

call_api

Parameters

Arguments Structure

Input Schema

Example Call

Success Response

Error Responses

Credential Resolution

Behavior Notes

Common Error Handling

Parameter Validation

Operation Format

Session Context

Exceptions

MCP Protocol Details

Protocol Version

Tool Annotations

Message Format

Best Practices

Discovery First

Type Learning

Authorization Handling

Error Recovery

Next Steps