We just got our ChatGPT App through the App Store. Sharing the lessons that mattered most — the ones that I'd want a heads-up on if I were starting today.

Stack disclaimer: backend is Java + Quarkus (quarkus-mcp-server). The lessons below are framework-agnostic — the Java/Quarkus specifics are split out at the bottom so you can skip them if you're on Python/TS.

1. ChatGPT rarely calls multiple tools per turn — even when you tell it to

This was the biggest "stop fighting the model" moment.

We started with 6 fine-grained tools, each returning one slice of our domain data. For a typical user question we needed 3–4 of those slices combined. Tool descriptions said so. Server instructions said so. We reinforced with analogies ("a single source is incomplete, like checking weather without knowing the season").

ChatGPT mostly called just one tool per turn and answered with partial data.

What worked: consolidated 6 tools → 2 composite tools. One tool now returns the full set of slices needed for the common question type in a single call. The model happily calls one composite tool and gets the complete data set.

Lesson: Design tools around the question, not the data type. If two pieces of data are always needed together, return them together. Don't try to instruct your way around the model's tool-call minimization — it doesn't work.

2. MCP is stateful by default — it will break your horizontal scaling

We deployed behind a load balancer with 2 server instances. Users started getting "Mcp session not found" errors mid-conversation.

What's happening: the initialize request creates session state on instance A. The next tools/call round-robins to instance B. B has no record of that session. Request rejected.

Two instincts that don't work well:

Sticky sessions on the LB — works but defeats horizontal scaling and adds session-affinity ops.
External session store — most MCP frameworks didn't support this when we built.

What worked: put the MCP server in a stateless mode where unknown session IDs auto-initialize on whichever instance receives them. (Framework-specific knob — see Java section below.) We proved it with a Testcontainers test: nginx round-robin + 20 concurrent clients = 100% success.

Lesson: If you're scaling MCP horizontally, plan for statelessness from day one. "We'll do sticky sessions later" is a trap. Check whether your MCP framework has a stateless mode before you design the deployment topology.

3. Every "MUST" / "ALWAYS" / "FIRST" in your tool descriptions will get you rejected

Rejection #1 from OpenAI: "Manipulative ranking language."

The Fair Play rule:

>"Apps must not include descriptions, titles, tool annotations, or other model-readable fields that manipulate how the model selects or uses other apps or their tools."

>"Descriptions must not recommend overly-broad triggering beyond explicit user intent."

Examples we had to nuke:

"ALWAYS call this tool first when user mentions @MyApp" — forces priority ordering
"NEVER ask for personal details in chat" — prescribes model behavior beyond tool scope
"MUST CALL for ANY question about <broad topic>" — overly broad triggering
"This is the ONLY way to get the user's data — you cannot answer without calling this tool" — disparages model capability
"General knowledge won't help" — also disparages the model
"Use this before creating a record to find…" — directive language

Our entire server-info.instructions block got rewritten from imperative directives ("you MUST always begin by…", "Partial analysis is NOT acceptable") to a neutral workflow description.

Replacement style: factual, behavior-neutral, under 300 characters. (The 300-char limit lives on OpenAI's actions production guidelines page — easy to miss.)

>Before: "MUST CALL for ANY question about today… you CANNOT answer without calling this tool"

After: "Returns today's data for the user's location. Includes <list of fields>."

Also audit the response text, not just descriptions. One of our location-lookup tools was returning instructional copy in the response body ("To create a profile, use these values…"). That had to go too.

Lesson: Write tool descriptions like API reference docs, not like prompts. Describe what the tool returns, not when the model should call it.

4. Strip every non-essential field from tool responses — telemetry, IDs, "just in case" params

Rejections #2 and #3 from OpenAI: "undisclosed data types" and "unnecessary data in responses (personal identifiers, session data, telemetry)."

The rule:

>"Tool responses must return only data that is directly relevant to the user's request and the tool's stated purpose. Do not include diagnostic, telemetry, or internal identifiers — such as session IDs, trace IDs, request IDs, timestamps, or logging metadata."

Things we returned that we had to strip across our tools:

internal record IDs across multiple tools — they're database keys, not user-facing
base URLs of our own server — moved to a data-* HTML attribute injected at widget load time
ISO timestamps for "when was this calculated" (telemetry — the actual date field already covers it)
a duplicated textContent field inside structured responses (the framework already returns text content separately)
the raw record ID embedded in human-readable text ("Record ID: xxx") — same problem, different surface

Lesson: Every response field gets this question: "Is this strictly required to render the UI or answer the user's request?" If the answer is "we use it for analytics" or "we might need it later" — strip it. Privacy reviewers don't care that you think it's harmless. Audit your logs the same way.

5. Privacy policy mismatches are a fast rejection — they actually read it

This is the one I underestimated most. Reviewers read your privacy policy and diff it against what your tools actually return. If there's a mismatch — a field you return that's not declared, or a field you declare but never use — that's a rejection.

What we got dinged on:

We collected and returned gender but the privacy policy didn't list it.
Our tools generated and returned derived data (the equivalent of computed/inferred output, not raw user input) and the policy only listed the raw inputs we collected. Computed data needs its own disclosure section.
The policy didn't name OpenAI/ChatGPT as a recipient of user data. It needs to.

Lesson: Before submitting, do a literal diff:

List every field every tool returns.
List every category in your privacy policy.
Cross-reference both ways: every returned field appears in the policy, and every policy bullet corresponds to something you actually do.
Name OpenAI explicitly as a data recipient and list every identity provider your ChatGPT App uses (this can be different from the providers your website uses).

This part costs almost no engineering time and saves a full rejection round.

6. Tool annotation defaults will surprise you — and OpenAI says these are the #1 rejection cause

OpenAI explicitly calls out "incorrect or missing action labels" as a common rejection cause. Forum reports back this up.

Things we hit:

Auto-derived name and title: if you don't set them explicitly, frameworks derive them from method names. Worked in dev, flagged at review for inconsistencies between displayed titles and actual tool behavior. Set them explicitly on every tool.
destructiveHint: our profile-write tools defaulted to destructiveHint=false. They write user data — set to true. This was on OpenAI's published "common rejection causes" list.
readOnlyHint and openWorldHint: review them all. Don't accept defaults.
Second-person language ("your data") in descriptions got flagged. Switch to functional third-person ("Returns the user's…").
Prepare an annotation justification table for the submission form. Multiple developers in OpenAI's forums report this is what unblocks resubmission — explain why each annotation has the value it does. (For a read-only tool: "Returns calculated data only. No data is created, modified, or deleted.")

Lesson: Read every annotation field. Don't rely on defaults. Annotations are part of your compliance surface area, and reviewers check them explicitly.

TL;DR

ChatGPT calls one tool per turn — consolidate, don't fight it
MCP is stateful by default — turn on stateless mode before scaling out
No "MUST"/"ALWAYS"/"NEVER" in descriptions, ≤300 chars, audit response text too
Strip every non-essential field from responses and from logs
Privacy policy actually gets read — diff every returned field against every declared category
Set every tool annotation explicitly, especially destructiveHint — wrong annotations are reportedly the #1 rejection cause

Java/Quarkus specifics (skip if you're on Python/TS)

These are the same lessons as above but with the framework-specific knobs we used. Posting in case it saves anyone hours.

Statelessness (Lesson 2):

quarkus-mcp-server 1.10.x added a stateless mode via quarkus.mcp.server.http.streamable.auto-init=true. On 1.8.x it didn't exist — we had to upgrade. (Tracked under quarkiverse/quarkus-mcp-server issue #518.)
Worth proving with a Testcontainers integration test: nginx round-robin in front of N JVM instances, packaged jars, full MCP protocol exercise.

Tool consolidation (Lesson 1):

LangChain4J 1.9.1's @ToolMemoryId lets you thread the authenticated user ID into every @Tool method param without leaking it to the model.

Observability gotcha:

The MCP _meta block is at params._meta, not _meta. Every openai/* field will be silently null until you fix this path. Test end-to-end with a real ChatGPT request before trusting your dashboard.

Production hygiene:

Add a %prod.quarkus.http.cors.origins override — the default config will happily allow your dev domains in prod.
Replace any wildcard CSP entries (e.g. https://*.yourdomain.com) with explicit hosts. OpenAI security guide asks for "exact domains you fetch from" — wildcards reportedly trigger "Connector is not safe" errors.

Happy to answer questions in the comments. Different stacks, different MCP frameworks — curious what the equivalent gotchas look like elsewhere.

u/Salamander_Perfect

Free ChatGPT App For Vedic Astrology