Add docs for arcade-java and Spring AI guide

[bdemers]

TODO:

• Add Spring AI guide

[vercel]

@bdemers is attempting to deploy a commit to the Arcade AI Team on Vercel.

A member of the Team first needs to authorize it.

[vfanelle]

Review notes

Followed the tutorial end-to-end locally using the Spring AI guide. Here's what I found.

What works

• arcade-spring-boot-starter is published to Maven Central at 0.1.0-alpha.5 — the dependency resolves correctly
• Spring Boot app starts and connects to OpenAI successfully
• Slack tool auth flow works end-to-end: first request returns an OAuth URL, after authorization the message sends correctly

Issues

Gmail context overflow

Gmail.ListEmails returns full email content for all matching emails. When the LLM calls this tool, Spring AI adds the entire result to the conversation context before making a follow-up call to OpenAI. With a real inbox this easily exceeds GPT-4o's 128k token limit, causing a 500 error. The tutorial's curl example ("List my recent emails") triggers this immediately.

Suggested fixes:

1. Add a n_results parameter to the listEmails @tool method so the LLM can request a bounded set:

@Tool(name = "list_emails",
      description = "List recent emails from the user's Gmail inbox")
public String listEmails(
    @ToolParam(description = "Search query, e.g. 'in:inbox'") String query,
    @ToolParam(description = "Maximum number of emails to return (default 5, max 10)") int maxResults) {
  return executeTool(
    "Gmail.ListEmails",
    Map.of("query", query, "n_results", maxResults)
  );
}

2. Add a callout warning:

<Callout type="warning">
Email tools can return large amounts of data. Ask the LLM for a specific number of emails (e.g. "list my 3 most recent emails") to avoid exceeding the model's context limit.
</Callout>

Note: The TanStack AI tutorial already handles this with a truncateDeep helper — worth considering a similar approach here.

Curl example channel

#general is the highest-visibility channel in most Slack workspaces — not a great default for a tutorial where someone might run it without thinking. Changed to #random and updated the message to mention Arcade:

curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Send a Slack message to #random saying hello from my Arcade-powered AI agent"}'

Changes made

• Updated the Slack curl example: #general → #random, message updated to "hello from my Arcade-powered AI agent"
• Added a Complete code section at the bottom (matching the TanStack tutorial pattern) with collapsible blocks for pom.xml, application.properties, ArcadeToolProvider.java, and ChatController.java

Open questions

• What Spring Boot and Spring AI versions should be pinned in the complete code pom.xml? The Spring Initializr generated 3.5.12 and Spring AI 1.1.3 — those are the tested versions. Using 3.5.0/1.1.0 as the base is cleaner but may not reflect what users actually get from the Initializr.
• Should the listEmails tool add a n_results parameter in this PR, or is that a follow-up?

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Mar 21, 2026 0:30am

[vfanelle]

Approving to merge. I'll follow up with a separate PR for the curl example update (#general → #random, Arcade mention in message) and the complete code section.