Another lesson from testing across hosted AI builders: MCP means every agent can call your service, but it doesn't mean every agent can actually use it.
- The same instruction can work perfectly in one environment and fail badly in another: eg "show the user the sign-in link, then wait for them to finish" works fine in a terminal agent that streams output as it works
- in a builder that doesn't show anything until the turn finishes, the agent can be patiently waiting for the user while the user is staring at a spinner and never sees the link
- "open this link for the user" works on a laptop, but in a hosted agent it runs in a cloud sandbox, where nobody can see it
- even setup differs: persistent instructions go into workspace knowledge on one platform, a skill on another, a skill plus switching the connector on in every chat on a third, and one needed nothing at all
- then there's where the generated code runs: some builders put your API call in server code; others put it in the browser, which suddenly means CORS matters
- redirects that are invisible in your normal setup can fail
- generated project structures differ enough that even assumptions like "there will be a src/ directory" aren't safe
So there are at least two layers of compatibility:
1 can the agent technically call your tools?
2 does the surrounding environment let the agent use them correctly?
MCP helps with 1, but 2 is still hard.
I've been testing what it takes to make an external service work well inside hosted AI builders (Replit, Lovable, etc). Not official integrations for now, just MCP. Some notes on MCP and AX:
- on a hosted builder, your MCP tool descriptions are basically your whole onboarding
- with Claude Code or another local agent you can ship rules files, project instructions, docs, etc. With hosted builders, you generally can't ship that context yourself; the user has to manually add in a nonobvious UI (and most won't IMO)
- that means don't treat tool descriptions like tiny API reference blurbs, biut rather as instructions that explain when the tool should be used, what assumptions to make, what to do before/after calling it, etc.
- so “tool description” is a slightly misleading term. In agentic systems it's closer to a compact operating manual attached to the capability
- I assumed shorter + cleaner was obviously better. Now I think the measure is decisions per token, not tokens. Guidance that stops the agent from making a wrong call is cheap at almost any length; reference detail the agent could fetch later isn't cheap.
- related: keep tool results boring. Results should mostly be data; instructions should live in the description
- some platforms inspect tool output and can suppress things that look like commands. If an auth response says something like "end your turn and run open <url>", there is a nonzero chance the user never sees it
- agents take returned fields literally. Don't use false to mean 'we don't know.' If a value is a guess, a default, or extracted by a model, say so in the response, because the agent will treat it as a rule.
- this matters more than it sounds. A human might skim past a weird field. An agent may use it as a hard constraint and decide not to use your service at all
- they cross-check you against yourself. If your tool description defines a term and your data doesn't fit the definition, or your docs and your responses disagree, assume the agent will notice, and that it may trust you less for the rest of the session.
Overall the machine-readable surface of a product is part of the product, not documentation about it.