Bug: Tool does not pass through filters well

[mattzcarey]

There is a problem with very heavily nested arguments to tools. This occurs when you see filters. You see that they are not passed through to the underlying api well.

Please investigate the issue.

The docs for stackone can be found here

[mattzcarey]

@claude please work on this.

[claude]

Claude finished @mattzcarey's task in 6m 38s —— View job • claude/issue-38-20250606_164935 • Create PR ➔

---

Filter Bug Fix Complete ✅

Fixed the issue with heavily nested filter arguments not being passed through to the StackOne API properly.

Todo List:

• Read repository setup instructions (CLAUDE.md)
• Analyze current filter implementation in codebase
• Examine parameter mapping and request building modules
• Check StackOne toolset implementation
• Review existing tests for filter handling
• Investigate StackOne API documentation for proper filter format
• Identify root cause of nested filter argument issue
• Implement fix for nested filter handling
• Test the fix and ensure compatibility
• Run linting/testing if available
• Commit changes

Root Cause ✅

The issue was in src/modules/requestBuilder.ts:149 where complex filter objects were being converted to [object Object] instead of proper deep object query parameter format.

Solution Implemented ✅

Added deep object serialization for query parameters:

1. serializeDeepObject() method: Recursively converts nested objects to proper query parameter format
2. shouldUseDeepObjectSerialization() method: Identifies when to apply deep object serialization (for filter and proxy parameters)
3. Enhanced execute() method: Uses appropriate serialization based on parameter type

Examples of the fix:

• ❌ Before: {filter: {updated_after: "2020-01-01"}} → filter=[object Object]
• ✅ After: {filter: {updated_after: "2020-01-01"}} → filter[updated_after]=2020-01-01

Supports deeply nested objects:

• {filter: {nested: {level2: {deep: "value"}}}} → filter[nested][level2][deep]=value

Test Results ✅

• Added comprehensive test cases covering basic and deep nesting scenarios
• All core module tests pass (27/27)
• Maintains backward compatibility for non-filter parameters
• Properly handles null/undefined values

Files Modified ✅

• src/modules/requestBuilder.ts - Core fix implementation
• src/modules/tests/requestBuilder.spec.ts - Test coverage

Changes Committed ✅

Committed fix with SHA: 5eaea8ba85f1608a0c0bb66a23bf1cd41a1c9dfb

The heavily nested filter arguments issue is now resolved! Filter and proxy parameters will be properly serialized as deep object query parameters, allowing complex filtering to work correctly with the StackOne API.

[mattzcarey]

@claude

Great job claude.

We have another issue I want you to build on the last change.

Very deeply nested schemas can take up alot of tokens in the prompt. We should truncate very nested params. and also have a tool which individually gets the full params for a tool name. we should direct the model to that if they have sent us the truncated params.

[claude]

Claude finished @mattzcarey's task in 12m 59s —— View job • Create PR ➔

---

Schema Truncation Feature Implementation ✅

Building on the previous filter parameter fix to optimize token usage by truncating deeply nested schemas.

Todo List:

• Read repository setup instructions (CLAUDE.md)
• Analyze current toolset implementation and schema handling
• Understand how parameters are currently structured and generated
• Design schema truncation logic with configurable depth limits
• Implement schema truncation functionality
• Create new tool for retrieving full parameter schemas by tool name
• Modify existing toolsets to use truncated schemas by default
• Add guidance/hints to direct models to full schema tool when needed
• Create examples demonstrating the new functionality
• Add comprehensive test coverage
• Run linting and testing
• Commit changes and provide PR link

Implementation Complete ✅

Core Features Implemented:

1. Schema Truncation Utility (src/utils/schema.ts):

   • truncateSchema() - Recursively truncates JSON schemas at configurable depth
   • isSchemaTruncated() - Detects if a schema has been truncated
   • Configurable options: maxDepth, truncation message, indicator flags
   • Handles complex schemas: nested objects, arrays, allOf/anyOf/oneOf

2. Enhanced Toolset Configuration:

   • Added schemaTruncation option to BaseToolSetConfig
   • Updated OpenAPIToolSet and StackOneToolSet to apply truncation
   • Full schemas stored separately for fallback access

3. GetFullSchema Tool (src/tools/getFullSchema.ts):

   • Special tool automatically available when truncation is enabled
   • Retrieves complete untruncated schemas by tool name
   • Provides clear guidance to models when schemas are truncated

4. Integration Points:

   • Works with OpenAI format (tool.toOpenAI())
   • Works with AI SDK format (tool.toAISDK())
   • Maintains backward compatibility when truncation disabled

Usage Examples:

// Basic truncation
const toolset = new StackOneToolSet({
  schemaTruncation: { maxDepth: 2 }
});

// Custom configuration
const toolset = new OpenAPIToolSet({
  filePath: 'spec.json',
  schemaTruncation: {
    maxDepth: 3,
    truncationMessage: 'Schema truncated - use getFullSchema for details',
    addTruncationIndicator: true
  }
});

// Get full schema when needed
const fullSchemaResult = await getFullSchemaTool.execute({ 
  toolName: 'hris_create_employee' 
});

Test Coverage ✅

• 11/11 tests passing for schema truncation functionality
• Tests cover basic truncation, nested objects, arrays, schema combinations
• Integration tests verify OpenAPIToolSet behavior
• Edge cases handled (disabled truncation, missing tools, etc.)

Token Savings Benefits ✅

• Configurable Depth: Control how deep schemas go (default: 3 levels)
• Automatic Fallback: getFullSchema tool provides complete details when needed
• Transparent Operation: Models get clear hints about truncated content
• Backward Compatible: No breaking changes when feature disabled

Changes Committed ✅

Committed comprehensive schema truncation implementation with SHA: 82a0bf3

Files Modified:

• src/utils/schema.ts - Core truncation logic
• src/toolsets/base.ts - Base configuration and getFullSchema integration
• src/toolsets/openapi.ts - OpenAPI toolset truncation support
• src/toolsets/stackone.ts - StackOne toolset truncation support
• src/tools/getFullSchema.ts - Fallback tool for complete schemas
• examples/schema-truncation.ts - Usage examples and demos
• src/tests/schema-truncation.spec.ts - Comprehensive test suite

---

Summary: Successfully implemented configurable schema truncation feature that reduces token usage for deeply nested parameters while maintaining full functionality through automatic fallback mechanisms. The feature is fully tested, documented, and ready for use.

---