[TEST][MOAR] Tools with complex request bodies

[jottakka]

Proposed solution for API with complex request bodies

Sample interaction in arcade chat: https://chat.arcade.dev/chat/26946170-bab4-403b-996d-0bbd55f80315

Complex API Tools - Execution Flow

Problem: LLMs struggle with complex nested API request bodies that can't be represented as simple tool parameters.

Solution: Dual-mode tools with stringified JSON inputs.

---

How It Works

Two Modes:
• GET_REQUEST_SCHEMA - Returns the OpenAPI schema with instructions
• EXECUTE - Validates and executes with the JSON input

Workflow:

1. LLM calls tool in schema mode ONCE (if needed)
2. Tool returns: {request_body_schema: {...}, instructions: "..."}
3. LLM builds the JSON object using the schema
4. LLM calls tool in execute mode with stringified JSON
5. Tool validates with full JSON Schema (oneOf, anyOf, patterns, formats, etc.)
6. Returns success or RetryableToolError with schema included

---

Key Prompt Design

Docstring:

"Only call schema mode if you don't already have it. Do NOT call repeatedly."

Instructions field:

"Do NOT call the schema mode again - you already have the schema now."

Disclaimer:

"Understanding the request schema is necessary to properly create the stringified JSON input object."

Error messages:
Include full schema to guide recovery without requiring another schema call

---

Result

✅ LLMs fetch schema once, then execute directly - no redundant calls
✅ Works for complex APIs with payment methods, nested objects, conditional fields, etc.

I believe we could implement this into more ⚠️ ASAP ⚠️, so the post functionalities are there as well, while we think in better solutions to solve the issue. APIs toolkits missing those creation/update tools wont be so useful, at least have it there can give the possibility to call those.

:60fps_parrot: PS: I will try to get some evals for this, but the chat interactions already give me better results than having a extra tool to get the scheme.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
arcade-ai-arcade-mcp-python	Building	Preview		Oct 13, 2025 4:41pm

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[EricGustin]

@jottakka This is an interesting approach and I support giving it a shot!