Problem
Executor is one MCP endpoint in front of every integration. That makes the catalogue easy, but it leaves per-integration guidance with nowhere to live:
- Server
instructions are one block for the whole server. Anything put there is loaded for every task, whether Drive is involved or not.
- The connection
description is the only per-integration text field. Executor's own wording says agents read it "from connections.list when they pick an account" - but reading the connection list is only an optional step of the execute skill. An agent that goes tools.search -> tools.describe.tool -> call never sees it.
Concrete case: we keep a company Drive with a documented folder convention. The rule now sits in the Google Drive connection description. An agent that works in Drive without calling connections.list never learns it and writes files wherever it wants.
A second, related problem: when a user says "use Google Drive", the agent often does not realise the app is reachable through Executor at all (see #1966).
Requested behaviour
- A connection (or integration) can carry a short guidance note, authored in the console the same way the connection description works today.
- That note is returned with the results of
tools.search (and ideally tools.describe.tool) for tools of that integration, e.g. as integrationGuidance next to the tool list.
- The note therefore enters the agent's context exactly when that integration is being used, and stays out of context for every other integration. No server-wide bloat, no extra call.
- The note is also the natural place for the first hop: "this app is reachable through Executor".
Why this pattern is proven
Composio does exactly this with skills: calling COMPOSIO_SEARCH_TOOLS returns recommended_plan_steps, known_pitfalls and difficulty in the same response as the tool slugs. From their docs: "Because the skill arrives inside the search response, it lands in your agent's context before the first execution." There, skills are part of search results by default and there is no opt-out.
How this differs from the current skills work
#1918 pins skills to the MCP Skills Extension (SEP-2640) and deliberately keeps skills.search / skills.get out of general tools.search. #1442 proposes a central skill store with per-agent sync. Both are useful, and neither covers this case: an always-on, integration-scoped note that arrives by itself, with no extra call, no install and no sync.
Notes
- Prefer the field on the connection over the integration, so different accounts of the same integration can carry different rules.
- A cap (e.g. 512 characters) keeps it a note rather than documentation.
Related: #1442, #1966, #1918, #1986.
Problem
Executor is one MCP endpoint in front of every integration. That makes the catalogue easy, but it leaves per-integration guidance with nowhere to live:
instructionsare one block for the whole server. Anything put there is loaded for every task, whether Drive is involved or not.descriptionis the only per-integration text field. Executor's own wording says agents read it "fromconnections.listwhen they pick an account" - but reading the connection list is only an optional step of the execute skill. An agent that goestools.search->tools.describe.tool-> call never sees it.Concrete case: we keep a company Drive with a documented folder convention. The rule now sits in the Google Drive connection description. An agent that works in Drive without calling
connections.listnever learns it and writes files wherever it wants.A second, related problem: when a user says "use Google Drive", the agent often does not realise the app is reachable through Executor at all (see #1966).
Requested behaviour
tools.search(and ideallytools.describe.tool) for tools of that integration, e.g. asintegrationGuidancenext to the tool list.Why this pattern is proven
Composio does exactly this with skills: calling
COMPOSIO_SEARCH_TOOLSreturnsrecommended_plan_steps,known_pitfallsanddifficultyin the same response as the tool slugs. From their docs: "Because the skill arrives inside the search response, it lands in your agent's context before the first execution." There, skills are part of search results by default and there is no opt-out.How this differs from the current skills work
#1918 pins skills to the MCP Skills Extension (SEP-2640) and deliberately keeps
skills.search/skills.getout of generaltools.search. #1442 proposes a central skill store with per-agent sync. Both are useful, and neither covers this case: an always-on, integration-scoped note that arrives by itself, with no extra call, no install and no sync.Notes
Related: #1442, #1966, #1918, #1986.