alivirgo Tool Schema Pruning Protocol (Function Calling Minification)
Overview
When configuring autonomous agents with Tool / Function Calling capabilities (OpenAI tools: [...] or Anthropic tools: [...]), frameworks inject complete JSON Schema definitions for every available tool into the input context.
In systems with 15 to 25 tools, bloated JSON Schemas with verbose parameter descriptions, empty example arrays, and redundant titles consume 4,000 to 8,000 input tokens on every single turn. This "Schema Tax" is paid on every user message and tool result, accounting for up to 50% of the entire session token bill.
The Tool Schema Pruning Protocol eliminates decorative metadata, strips self-evident descriptions, and dynamically exposes only the tools relevant to the active operational phase.
Bloated JSON Schema vs. Pruned High-Density Schema
┌─────────────────────────────────────────────────────────────┐
│ Tool Schema Token Footprint │
│ │
│ Bloated JSON Schema (320 Tokens per Tool): │
│ { │
│ "name": "view_file", │
│ "description": "This tool allows the agent to view the │
│ contents of a file from the local filesystem...", │
│ "parameters": { │
│ "type": "object", │
│ "properties": { │
│ "AbsolutePath": { │
│ "type": "string", │
│ "description": "The full absolute path to the file │
│ that you want to read from the disk...", │
│ "examples": ["/src/index.ts"] │
│ } │
│ } │
│ } │
│ } │
│ │
│ Pruned High-Density Schema (55 Tokens - 82.8% Cut!): │
│ { │
│ "name": "view_file", │
│ "description": "Read file slice by line range.", │
│ "parameters": { │
│ "type": "object", │
│ "properties": { │
│ "AbsolutePath": {"type": "string"}, │
│ "StartLine": {"type": "integer"}, │
│ "EndLine": {"type": "integer"} │
│ }, │
│ "required": ["AbsolutePath"] │
│ } │
│ } │
└─────────────────────────────────────────────────────────────┘
The 3 Schema Pruning Rules
1. Strip Obvious Parameter Descriptions
Do not explain self-evident parameter names:
- ❌ Bad:
"Query": {"type": "string", "description": "The exact string query to search for"} - 🟢 Good:
"Query": {"type": "string"}
2. Purge Decorative JSON Schema Keywords
Strip title, $schema, examples, default: null, and additionalProperties: false from tool definition payloads.
3. Dynamic Tool Subsetting
Do not send all 25 tools on every turn. Dynamically expose tool sets by active mode:
- Planning Phase:
[view_file, grep_search, list_dir](3 tools) - Execution Phase:
[view_file, replace_file_content, run_command](3 tools) - Browser Phase:
[browser_subagent, read_url_content](2 tools)
Production Python Schema Pruner Middleware
from typing import Dict, Any, List
def prune_tool_schema(tool_def: Dict[str, Any]) -> Dict[str, Any]:
"""Strips verbose titles, empty examples, and redundant descriptions from tool schema."""
fn = tool_def.get("function", tool_def)
params = fn.get("parameters", {})
# 1. Clean properties
clean_props = {}
for prop_name, prop_val in params.get("properties", {}).items():
clean_prop = {"type": prop_val.get("type", "string")}
# Keep description ONLY if non-obvious or contains enum/formatting constraints
if "enum" in prop_val:
clean_prop["enum"] = prop_val["enum"]
if "description" in prop_val and any(k in prop_val["description"].lower() for k in ["1-indexed", "format", "must", "optional"]):
clean_prop["description"] = prop_val["description"]
clean_props[prop_name] = clean_prop
return {
"type": "function",
"function": {
"name": fn["name"],
"description": fn.get("description", "").split(".")[0], # 1-sentence summary
"parameters": {
"type": "object",
"properties": clean_props,
"required": params.get("required", [])
}
}
}
Benchmark Comparison
Session with 15 registered agent tools across a 30-turn coding task:
| Schema Management | Baseline Tool Input Tokens / Turn | Cumulative Tool Token Spend | Cost Savings |
|---|---|---|---|
| Full Unpruned Tool Schemas | 4,600 tokens / turn | 138,000 tokens | Baseline ($0.414) |
| Pruned Schema + Dynamic Subsetting | 680 tokens / turn | 20,400 tokens | 85.2% Cost Reduction ($0.061) |
Agent Operational Directive
MANDATORY: Agent orchestration frameworks must sanitize tool schemas before passing them to the API. Strip verbose parameter descriptions and dynamically subset the exposed tools to match the active operational phase.