Checklist
Go through this list before you share a Connector. Each item is covered in more detail elsewhere in this section, and most of them are things that fail silently or confuse the model if they are missed.
Names
- [ ] The Connector's name gives a sensible slug, and
{connector slug}__{tool slug}is under 64 characters for every tool. - [ ] Tool slugs are short
snake_caseverbs, such assearch_issues. - [ ] Input names and auth profile names are valid Python names, and not keywords.
- [ ] Every input that names a file or folder has its Path set.
- [ ] No tool's Uses auth row shows a name in red.
Where It Runs And How It Signs In
- [ ] Tools that work with the person's computer are in a Client — connected desktop Connector; tools that call web APIs are in a Server — gateway runtime Connector.
- [ ] A Client Connector uses only Static credential profiles.
- [ ] Credentials come from
auth.<name>, never from an input, a default value or the code. - [ ] Each auth profile's description says where to get the credential.
Scripts
- [ ]
resultis set at the top level, on every path — including errors. - [ ]
resultholds only JSON types, and a typical result is under about 11,000 characters, with hard limits on lists and long text. - [ ] Expected failures return
{"error": "<what happened, and what to do next>"}. - [ ] Optional inputs cope with
None, and numbers are clamped. - [ ] No
sys.exit(), no reading from standard input, no subprocess that might wait for input, and no relative paths. - [ ] Every network call and subprocess has its own timeout, shorter than the tool's.
- [ ] The tool's Timeout (seconds) is set.
- [ ] Only the standard library and the bundled packages are used — or the extra packages are listed under Python dependencies, and the description says why.
- [ ] Any environment variable a tool needs, other than the minimal set, is listed under Environment variables.
- [ ] A tool that returns images also describes them in text.
- [ ] Each tool has been run in the debug runner with realistic inputs, including a failure, and tried in a chat.
Descriptions
- [ ] Every tool's AI Description says what it returns, when to use it, and which other tool to use instead.
- [ ] Every input's description gives its format, its default and its limit.
- [ ] The Connector's description tells an administrator what to set up: credentials, Constant input values, and Python packages.
- [ ] The Version has been raised since the last file you shared.
What A Connector Cannot Do
Some things are outside what a Connector can do. If what you need is on this list, look for the nearest design that works.
| A Connector cannot | Instead |
|---|---|
| Remember anything between calls | Every call is a fresh process. A Client tool can keep a file somewhere you choose; a Server tool should rely on the system it talks to |
| Act as the person using it | Credentials are one per installation, and a tool does not know who called it |
| Report progress or ask a question while it runs | Return a result, and let the model ask the person |
| Run on a schedule, or react to events | Tools run only when a model calls them. Use a Scheduled Task that calls the tool |
| Return a file | Return text, a path (Client Connectors), or a link. Pictures can be returned — see Returning images |
| Run in web chat or on the API, if it is a Client Connector | Make it a Server Connector, if what it does can run on the Gateway |
| Run code other than Python directly | A Client tool can run a program installed on the person's computer with subprocess. Check for it with shutil.which first, and fail with a clear error if it is missing |