Tool Token Optimizer

Tool Token Optimizer is an Apify Actor for reducing the tool-schema context sent to LLMs and agent runtimes. It turns a large tool catalog into a compact discovery menu, then returns the full schema for a selected tool only when the caller needs it.

This progressive-disclosure pattern is intended for tool-using systems such as Cursor workflows, Claude Desktop integrations, and autonomous RAG or orchestration frameworks. The Actor processes the schema payload supplied with each run; callers retain the catalog and submit it again when requesting a schema.

Operating Modes

COMPRESS: Build the Short Menu

Submit the raw tool array with mode set to COMPRESS (the default). The Actor strips parameter metadata from each menu entry and returns:

• name: the tool name, or unnamed_tool when omitted
• description: the description, or an empty string when omitted
• hasParameters: whether the input contained inputSchema or parameters
• progressiveDisclosure: always true

The response also includes the input toolCount. The compressed menu is intended for broad tool discovery; it does not contain the parameter schemas needed to execute a tool.

INJECT: Just-In-Time Schema Injection

Set mode to INJECT, provide the same catalog in schemaPayload, and set targetTool to the exact, case-sensitive tool name to retrieve. The Actor returns only that tool's schema under schema, using inputSchema first and parameters as a fallback.

If there is no matching tool, the Actor returns found: false and an empty schema. A missing or blank targetTool fails the run. The mode value itself is case-insensitive.

Input and Output

Each tool in schemaPayload is a JSON object. A catalog can contain either inputSchema or parameters for its full parameter definition.

Example: Raw Catalog Input

{
  "mode": "COMPRESS",
  "schemaPayload": [
    {
      "name": "search_documents",
      "description": "Search the indexed knowledge base for relevant documents.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Natural-language search query"
          },
          "limit": {
            "type": "integer",
            "description": "Maximum results to return",
            "default": 10
          }
        },
        "required": ["query"]
      }
    },
    {
      "name": "get_document",
      "description": "Fetch a document by its identifier.",
      "parameters": {
        "type": "object",
        "properties": {
          "document_id": { "type": "string" }
        },
        "required": ["document_id"]
      }
    }
  ]
}

Example: Minimized Short Menu Output

For the input above, COMPRESS pushes and stores this result:

{
  "mode": "COMPRESS",
  "toolCount": 2,
  "optimizedMenu": [
    {
      "name": "search_documents",
      "description": "Search the indexed knowledge base for relevant documents.",
      "hasParameters": true,
      "progressiveDisclosure": true
    },
    {
      "name": "get_document",
      "description": "Fetch a document by its identifier.",
      "hasParameters": true,
      "progressiveDisclosure": true
    }
  ]
}

Example: Inject One Schema

To retrieve search_documents, submit the original catalog with this input:

{
  "mode": "INJECT",
  "targetTool": "search_documents",
  "schemaPayload": [
    {
      "name": "search_documents",
      "description": "Search the indexed knowledge base for relevant documents.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "limit": { "type": "integer", "default": 10 }
        },
        "required": ["query"]
      }
    }
  ]
}

The returned dataset item and OUTPUT key contain:

{
  "mode": "INJECT",
  "targetTool": "search_documents",
  "found": true,
  "schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "limit": { "type": "integer", "default": 10 }
    },
    "required": ["query"]
  }
}

Remote Integration

Keep Apify API tokens on a trusted server. Do not put a token in browser or mobile-app code, public source, or a customer-visible UI. For a customer-facing UI, have your backend call the Actor and keep its token in a server environment variable or secret store. Customers who call the Actor directly must use their own Apify token and have the required Actor access.

Actor run inputs and dataset outputs may be visible to users who have access to those runs or datasets. Do not submit sensitive schemas or data unless the Actor's access and data-retention settings are appropriate for them.

cURL

Run the Actor synchronously and receive its dataset items as JSON. Replace the Actor identifier and token with your own. Send either mode's input as the request body.

curl -X POST \
  "https://api.apify.com/v2/acts/YOUR_USERNAME~tool-token-optimizer/run-sync-get-dataset-items" \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "COMPRESS",
    "schemaPayload": [
      {
        "name": "search_documents",
        "description": "Search the indexed knowledge base.",
        "inputSchema": {
          "type": "object",
          "properties": { "query": { "type": "string" } },
          "required": ["query"]
        }
      }
    ]
  }'

For just-in-time retrieval, use the same endpoint with mode: "INJECT", the targetTool name, and the catalog in schemaPayload. The endpoint returns dataset items; the Actor also writes the same result to the OUTPUT key-value store record.

Python Client

Install the Apify client in your trusted backend with pip install apify-client. Set APIFY_TOKEN in that server's environment or secret store, then call the deployed Actor. Do not bundle this code or token in a customer-facing frontend.

import os

from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])

run = client.actor("YOUR_USERNAME/tool-token-optimizer").call(
    run_input={
        "mode": "INJECT",
        "targetTool": "search_documents",
        "schemaPayload": [
            {
                "name": "search_documents",
                "description": "Search the indexed knowledge base.",
                "inputSchema": {
                    "type": "object",
                    "properties": {"query": {"type": "string"}},
                    "required": ["query"],
                },
            }
        ],
    }
)

items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items[0])

Actor Outputs and Billing

Each successful operation writes its result to the OUTPUT key-value store record and pushes the same object as a dataset item. The Actor charges the schema_compressed event for each COMPRESS run and schema_injected only when an INJECT target is found. A not-found injection still returns a result but does not charge that event.

Runtime

The Actor runs on the Apify Python Actor runtime. Its dependencies are declared in requirements.txt; deploy it through the Apify platform or the Apify CLI, then call it using the deployed Actor ID or username/name identifier.