Add typed tool composition with context.tools.execute()

[evantahler]

Summary

Feature Announcement Slides

Adds typed tool composition to arcade-mcp-server, allowing compound tools to call other tools with type safety and automatic response structuring. Also adds cross-tool requirement resolution so compound tools can declare upfront what auth/secrets their sub-tools need.

Tool Composition (context.tools.execute())

• New context.tools.execute(ResponseModel, tool_name, args) method for strongly-typed cross-tool calls
• 3-tier structuring strategy: direct Pydantic validation → heuristic mapping → LLM extraction (via MCP sampling or Anthropic SDK fallback)
• OnMissing.ALLOW_NULL for resilient field extraction when upstream responses change
• Automatic fallback to Arcade Cloud for tools not registered locally

Cross-Tool Requirement Resolution (requires_secrets_from / request_scopes_from)

• @tool(requires_secrets_from=["Gmail.ListEmails"], request_scopes_from=["Slack.SendMessage"])
• Fetches remote tool definitions from Arcade Cloud at startup via arcade.tools.get()
• Merges secrets and OAuth scopes into the compound tool's requirements
• MCP clients see the full requirements at tools/list time and can prompt for auth proactively
• No Arcade Cloud changes required

Multi-Provider Auth

• Compound tools referencing different OAuth providers (e.g. Google + Slack) now track all providers
• resolved_authorizations field stores the full list; exposed via _meta.arcade.requirements.authorizations
• Each provider is checked at execution time before the tool runs
• Single-provider tools work exactly as before (backward compatible)

Key Files

• libs/arcade-mcp-server/arcade_mcp_server/context.py — Tools.execute(), structuring, remote fallback
• libs/arcade-mcp-server/arcade_mcp_server/server.py — _resolve_cross_tool_requirements(), multi-provider auth checks
• libs/arcade-core/arcade_core/structuring.py — Tier 1-2 deterministic structuring
• libs/arcade-mcp-server/arcade_mcp_server/convert.py — authorizations list in MCP metadata
• examples/mcp_servers/email_to_slack.py — Full compound tool example

Test plan

• uv run pytest libs/tests/arcade_mcp_server/test_cross_tool_requirements.py — 19 tests for requirement resolution + multi-provider auth
• uv run pytest libs/tests/arcade_mcp_server/test_tool_composition_structuring.py — LLM extraction tests
• uv run pytest libs/tests/core/test_structuring.py — Tier 1-2 structuring tests
• uv run pytest libs/tests/ — Full test suite (2365 pass)
• make check — ruff + ruff-format + mypy clean (no new errors)
• Manual: run email_to_slack example, verify tools/list includes merged Gmail/Slack auth in _meta.arcade.requirements.authorizations

🤖 Generated with Claude Code

[JiwaniZakir]

The example in email_to_slack.py uses logger.warning() for routine informational messages ("Fetching emails with n_emails=%d" and "Gmail response: %s") — these should be logger.info() or logger.debug() since they represent normal execution flow, not degraded conditions. Using warning here will pollute logs in production deployments and undermine the signal value of that log level.

The Slack send loop in forward_emails_to_slack issues calls sequentially; for max_emails=5 this means up to 5 serial round-trips to Slack. Since each context.tools.execute() is async, these could be fanned out with asyncio.gather(), which would be meaningfully faster and is a more idiomatic pattern for this kind of fan-out composition.

ToolResponseExtractionError in errors.py carries no structured metadata about what failed — e.g., which field couldn't be mapped, what the raw response looked like, or which target model was being structured into. Adding optional fields like field_path and raw_value to the exception (or at least surfacing them in developer_message) would make these errors far easier to diagnose when OnMissing.ALLOW_NULL is not set and extraction actually fails.