Tool Parameter Handling

Tool Parameter Handling manages the translation, validation, and routing of arguments between Large Language Models (LLMs) and the StackOne API. This system ensures that schemas provided by the Model Context Protocol (MCP) server remain intact during model interactions and are correctly mapped to API requests for tool execution.

The SDK supports two primary calling surfaces with different parameter shapes: individual tools fetched via fetch_tools() and meta-tools used via search() and execute(). It handles complex parameter requirements, including flat-prefixed keys, nested envelopes, and binary file downloads.
Sources: CLAUDE.md:27-38, stackone_ai/tools.py:12-16

Parameter Architecture

The SDK acts as a pass-through layer for tool schemas. It preserves the original JSON Schema keywords to ensure models receive full context for argument generation.

The flow ensures that no information is lost between the server and the model.
Sources: stackone_ai/tools.py:560-565, CLAUDE.md:123-128

Key Data Structures

Sources: stackone_ai/types.py:102-109, stackone_ai/types.py:161-182

RPC Parameter Mapping

The StackOneRpcTool class handles the conversion of arguments into the StackOne /actions/rpc envelope. It supports a "flat-prefixed" parameter style, where keys indicate their destination location (e.g., path_id, query_limit).

Flat-Prefixed Splitting Logic

The _split_envelope_params method divides arguments into path, query, headers, and body buckets. It prioritizes flat-prefixed keys but also accepts nested containers for compatibility.

Argument Precedence

When resolving conflicts, the SDK follows a specific order:

1. Flat-prefixed keys (e.g., body_variables) take top priority.
2. Nested containers (e.g., {"body": {"variables": ...}}) are assigned next.
3. Bare keys default to the body bucket.
   Sources: stackone_ai/tools.py:734-740, tests/test_tool_calling.py:301-306

Schema Normalization

The SDK normalizes schemas for different AI frameworks while maintaining technical accuracy. It uses an internal nullable marker to track optionality, which is later converted to standard JSON Schema required lists for models.

Integration Formats

• OpenAI: Converts internal markers to the required list and strips SDK-specific keys.
• LangChain: Passes the JSON Schema to args_schema to prevent loss of nested field definitions.
• Pydantic AI: Uses Tool.from_schema to preserve the served structure.

# stackone_ai/tools.py:560-575
def to_openai_function(self) -> JsonDict:
    properties: JsonDict = {}
    required: list[str] = []

    for name, prop in self.parameters.properties.items():
        if isinstance(prop, dict):
            clean_prop = _strip_internal_keys(prop)
            properties[name] = clean_prop
            if not prop.get("nullable", False):
                required.append(name)

Sources: stackone_ai/tools.py:560-580, stackone_ai/tools.py:620-630, README.md:162-178

Binary and File Parameter Handling

Tool execution detects non-JSON responses to support file downloads. If the Content-Type is not JSON-based, the SDK returns raw bytes and metadata instead of attempting a UTF-8 decode.

Filename Sanitization

The SDK sanitizes filenames extracted from Content-Disposition headers to prevent path traversal attacks. It reduces names to safe basenames and strips control characters.
Sources: stackone_ai/types.py:126-146, tests/test_tool_calling.py:355-375

Security and Validation

The SDK implements several guards to ensure parameter safety:

• Header Allowlist: Only headers declared in the served schema are passed to the API. Model-supplied headers like Authorization are dropped.
• Path Encoding: Parameters mapped to the PATH location are URL-encoded to prevent SSRF or path injection.
• Argument Type Check: Execution requires arguments to be a JSON object; scalar values are rejected with a ValueError.
  Sources: stackone_ai/tools.py:417-430, stackone_ai/tools.py:456-465, tests/test_tool_calling.py:180-195

Summary

Tool Parameter Handling in the StackOne SDK prioritizes schema fidelity and secure routing. By supporting both flat-prefixed and nested argument shapes, the system allows for flexible integration across various AI frameworks while ensuring that API requests conform strictly to the definitions provided by the underlying SaaS connectors.