[5173] docs(design): plan — surface gateway tool-resolution failures and stop one dead tool bricking the agent

[mmabrouk]

Context

A committed agent config referenced the Composio action github/COMMIT_MULTIPLE_FILES, which Composio removed from its catalog. Every turn on that config failed in about six seconds with only:

Gateway tool resolution failed (HTTP 404)

The message named no tool and no reason. Diagnosing it required backend access: reading the saved config out of Postgres and probing each action slug against Composio by hand. This is QA finding F-019, and it reproduces the two problems in issues #5173 and #5174.

Two things are wrong. The failure is opaque, and resolution is all-or-nothing so one dead tool takes down an agent whose other tools are fine.

The root cause of the opacity is a one-hop drop. The backend already produces the useful sentence and puts it in the HTTP body ({"detail": "Action not found: composio/github/COMMIT_MULTIPLE_FILES"}). The SDK reads only the status code and discards the body.

What this adds

This is a design-only plan-feature workspace. No code changes. It plans two independently shippable fixes and settles where each one lives.

• Surface the detail end to end. Read the resolve response body in the SDK (gateway.py), pull detail out, and carry it on the exception so the run error reads Action not found: composio/github/COMMIT_MULTIPLE_FILES (HTTP 404) instead of a bare HTTP 404.
• Stop one dead tool bricking the agent. Resolve the survivors and drop only a genuinely-absent action, with a loud warning to both the model and the user. Keep connection, auth, and provider failures fatal, because those are actionable states, not dead tools.
• Keep Composio discover vs resolve toolkit-version misalignment: discover_tools surfaces tools that resolve/execute can't find #5174 separate. Composio discover vs resolve toolkit-version misalignment: discover_tools surfaces tools that resolve/execute can't find #5174 is the root cause (discover and resolve use different Composio version scopes). This plan is the symptom side, needed even after Composio discover vs resolve toolkit-version misalignment: discover_tools surfaces tools that resolve/execute can't find #5174 lands, because a committed agent still rots when Composio removes an action months later.

Before and after, from the user's point of view:

before:  Gateway tool resolution failed (HTTP 404)          # run dies, no tool named
after:   Gateway tool resolution failed: Action not found:  # run names the tool, or
         composio/github/COMMIT_MULTIPLE_FILES (HTTP 404)    # drops it and runs on with a warning

Workspace

docs/design/agent-workflows/projects/gateway-tool-resolution/: context.md, research.md (the verified failure chain, including the exact swallow point and run lifecycle), design.md (the three decisions with trade-offs), plan.md (three phases), status.md.

Notes

• Design only, so nothing to run. The failure chain in research.md is verified against the code at the current base.
• Draft. Three open questions in status.md need a decision before Phase 2 coding: the warning transport, whether any tool is "required", and who owns the shared resolvability check across this plan and Composio discover vs resolve toolkit-version misalignment: discover_tools surfaces tools that resolve/execute can't find #5174.

Closes the design step for #5173. Related: #5174.

https://claude.ai/code/session_018MaXPNpvzN22kngHno3VMj

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 10, 2026 10:52pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 52c9f6fb-bc12-49bd-ae7d-f591564ce747

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/gateway-tool-resolution-plan

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

Feedback needed. This plan is ready for review. Three open questions need a call before Phase 2 gets coded (details in status.md):

1. Warning transport for a dropped tool. When resolution drops a genuinely-absent action, where does the warning live: a run annotation, a trace event, or an SDK-injected system message? It must reach both the user and the model.
2. Are any tools "required"? If an agent's only useful tool is the dead one, dropping it and running tool-less may be worse than failing. Options: a per-tool required flag, or a rule that an empty surviving tool set fails rather than runs.
3. Ownership of the shared "can this action resolve" check. Both this plan (failure classification in Phase 2) and Composio discover vs resolve toolkit-version misalignment: discover_tools surfaces tools that resolve/execute can't find #5174 (validate-on-discover) need the same primitive. Whichever lands first should own it; confirm the order.

Phase 1 (surface the resolver detail in the run error) has no open questions and can be approved independently.