Tools and tool families

What a fresh connection already has

A default server serves an always-on base without anyone switching anything on:

• Base utilities and memory: the small always-useful set every agent leans on.
• The workspace database and workspace files.
• First-party people and company data, which has no per-call upstream of its own beyond your credits.
• Every curated data source, listed as a few grouped tools per source.
• Every vendor, connector, remote MCP server and vendor database the workspace has actually connected.
• The platform stack: agent lifecycle, schedules, queues, webhook management, knowledge bases, platform guidance, observability, agent invocation, the dashboard, data-pipeline management and vendor sync.

Registration is free, and no plan locks a family away: every plan gets every tool. Plans differ only in how much you can create and run, so a call that would cross a limit is refused at call time with an offer, never hidden from the list. Queues and the Slack channel-management tools are shipped and live.

The catalog is not the default

Curated pay-per-call data sources, every data:<slug> family, are on by default, and so is every vendor the workspace connects; both list a few grouped tools each instead of one tool per operation, except a vendor whose tools are not grouped yet. A fresh workspace still starts on a working set instead of the entire catalog, which is the difference between an agent that can choose and an agent drowning in a tool list.

Three more families stay off until someone deliberately turns them on, because they reach a real person or run code:

An agent can turn on what it is missing

A default server also carries a set of control tools, injected only there, never into a deployed agent's runtime catalog or a custom subset server. They are how a session discovers the rest of the platform without a dashboard round-trip.

1. 01

   Search

   agnt_tools_search returns matching families with their id, label, tool count and whether they are already enabled. Every attachable tool carries a config_ref object you can copy verbatim to wire that tool onto an agent; a tool with no config_ref is always-on base and cannot be attached.
2. 02

   Enable

   Pass family ids to agnt_tools_enable. The change is saved immediately and permanently, the server starts serving the new tools right away, and a tools/list_changed notification goes out.
3. 03

   Refresh the client

   Most clients ignore that notification, so the newly enabled tools may stay invisible for the rest of the session. That is expected and does not mean the enable failed. Direct-config clients pick them up on a new session or a reconnect; cloud-connector clients need the connector refreshed in its own settings first. The enable result spells out the steps per client, and agnt_tools_search always reports the true state even while your tool list is stale.

A refused call is an offer, not an error

When a call would cross one of the organization's plan limits (one schedule past the cap, a data call past the included credits, anything after a trial ends), it comes back as a normal tool result carrying a requires_upgrade offer: why it was refused, the limit with what is in use, the next plan with its price and what it unlocks, and a confirm URL. It is never a protocol error, because clients retry and bury errors while a result gets relayed to the person who can act on it. Nothing ran, so nothing was charged.

{
  "status": "requires_upgrade",
  "reason": "limit_reached",
  "message": "This organization has reached its schedules cap on the Starter plan (10 of 10); Growth ($149/mo) raises it to 50.",
  "tool": "agnt_schedules_create",
  "limit": {
    "resource": "schedules",
    "used": 10,
    "cap": 10,
    "tier": "builder_starter"
  },
  "current_tier": "builder_starter",
  "upgrade": {
    "tier": "builder_growth",
    "name": "Growth",
    "price_usd_month": 149,
    "included_data_credits_usd": 90,
    "unlocks": {
      "workspaces": 3,
      "agents": 15,
      "schedules": 50,
      "queues": 15,
      "webhookEvents": 150000,
      "dataJobPipelines": 15,
      "dataJobItems": 75000,
      "knowledgeCollections": 15,
      "knowledgeDocuments": 5000,
      "knowledgeStorageBytes": 21474836480,
      "dbTables": 50,
      "dbRows": 250000,
      "dbStorageBytes": 1073741824,
      "inboxes": 3,
      "messagingLines": 3
    }
  },
  "confirm_url": "https://app.superagnt.com/confirm/<token>",
  "human_step": "The call did not run: schedules are at the plan's cap. Everything that already exists keeps working. Nothing was charged. Share the confirm_url with a person on this account: they review Growth there and confirm it. You never pay or change the plan yourself. Retry once they have confirmed."
}

The reason says what happened and what the agent should tell the person:

A call into a vendor nobody has connected is refused the same way, with a structured result naming the vendor and a link to the connections page rather than an exception.

Some families are marked elevated in the catalog: lifecycle, bindings, schedules, queues, webhooks, vendor sync, knowledge, email, agent invocation and dashboards. That is display metadata the dashboard badges, not a gate: it tells a person which tools carry real authority. It refuses nothing.