Why tools/list is yours, and not a catalog
tools/list on CoreSpeed returns exactly what this sign-in can call. Absence is a decision, presence is neither health nor permission, so never hard-code it.
On CoreSpeed, tools/list is caller-specific: it returns exactly the tools this sign-in can call right now. A tool is absent because a capability is off or an app is not connected for this caller. A tool is present even when its account needs reauthorization, and even when this credential will be refused. Read it each session; never store it.
Why is a tool absent?
Absence is a decision, and it is usually one of these:
- The app is not connected for this caller.
notion__create_pageappears only when Notion is connected, privately by you or shared with the org. - The caller is an agent key. Agent principals reach shared connections only, so a member's private connections are missing from the agent's list.
- A built-in capability is off. Memory, Media, Web and Social can be disabled at the org or member level, and a disabled capability unregisters its tools.
- The environment does not offer the connector. A connector is served only where CoreSpeed holds credentials for it, and the answer differs by organization.
The same request from a teammate can return a different list. Two members with different connections and different capability settings get two lists; that is the design. The fix for a missing tool is in Dashboard → Connectors or Dashboard → Tools, never in client configuration.
Why is presence not health?
A connected account can reach needs_reauth: a refresh failed, the vendor named the credential invalid, or the org's own OAuth app was replaced. The connector stays known and its tools stay in tools/list. Calls fail until the member reauthorizes in Dashboard → Connectors.
So a listed tool is a tool you may try, and nothing more. The state of the account behind it is reported on the authenticated connectors index. Do not rotate the CoreSpeed key or rewrite the client config on needs_reauth; neither is broken.
Why is presence not permission?
Some tools are listed and then refuse this credential. The manage__keys_*, manage__agents_*, manage__accounts_*, manage__whoami and manage__switch_org tools run only under a member session. An API key sees them in tools/list and gets HTTP 200 with isError: true and the code jwt_session_required when it calls one. manage__remote_add, manage__remote_refresh and manage__remote_remove need an org admin, or a key whose creator is one.
Spend holds work the same way. Past the wallet threshold a metered tool is still listed and answers payment_required; past a key's monthly cap it answers key_spend_limit_exceeded. Under Smart Approval a listed write may be held or denied by policy. The list says what exists; the call says what this caller may do with it now.
| Situation | In tools/list? | What a call answers |
|---|---|---|
| App not connected for this caller | No | Nothing to call |
| Capability disabled for this member or org | No | Nothing to call |
| Agent key, member's private connection | No | Nothing to call |
Account in needs_reauth | Yes | needs_reauth |
| Session-gated tool, API key caller | Yes | jwt_session_required |
| Wallet past threshold | Yes | payment_required |
| Key past its monthly cap | Yes | key_spend_limit_exceeded |
| Write held by policy | Yes | Approval receipt, then manage__approval_wait |
How do capability controls shape the list?
Capability controls apply to the built-ins, Memory, Media, Web and Social, and never to connectors. They live at Dashboard → Tools. Built-ins are on by default. The org level is the ceiling; a member setting only narrows. Effective is org enabled and member enabled. Disabling unregisters the tools from tools/list and leaves the data in place.
Settings are per member per org. A member key follows its creator's settings; an agent key follows the agent's own. Connectors have no switch of this kind: connect and disconnect are the switch. The capability controls page covers the rules.
Where do you read account state?
The authenticated index is the only inventory of connectors and accounts:
curl https://api.corespeed.io/connectors \
-H "Authorization: Bearer $CORESPEED_API_KEY"It says which connectors are offered to this caller, which accounts exist with which aliases, how each was connected (auth.type), whether a pasted key was verified (key_verified), whether this caller may remove an account (can_remove), and the status of each account. It also keeps a live grant visible: an account you hold on a connector that stopped being offered stays in the index, and its tools stay in tools/list, until you disconnect it. The connectors page has the full account model.
What should a client do with the list?
Call tools/list at the start of every session, and again after the user connects something. Discovery costs 0 credits. Then branch on results: isError: true with structuredContent.error.code is the answer to "may I", and an HTTP 200 is never on its own a success. The errors page lists the codes that clear on retry and the ones that never do; needs_reauth, jwt_session_required, holds and caps are in the second group.
Never hard-code an inventory. A client that ships a list of CoreSpeed tools is wrong for every caller except the one it was written against, and it goes stale the first time someone disconnects an app. The MCP page describes the surface this way on purpose: tools are the agent's to discover, and the list is the caller's.
FAQ
My teammate sees linear__search_issues and I do not. Is that a bug? No. Linear is connected privately for them and not for you. Connect it at Dashboard → Connectors, or ask them to share it.
A tool is listed but every call fails with needs_reauth. What now? Reauthorize the account in Dashboard → Connectors. The key and the client config are fine.
Why does my API key see manage__whoami and get refused? It is session-gated. Verify a key with a free call such as memory__list_memory instead.
Does disabling a capability delete its data? No. Disabling unregisters the tools. The data stays.
Can I cache tools/list across sessions? Read it each session. It is free, and it changes whenever a connection, a capability setting or a credential changes.