Contributing to Thinky
This page is for people building a node kind on OpenX. Thinky, the workspace's assistant, knows a kind only through what the kind tells it: a short guide, a few named tools, and the context items its panels and canvases point Thinky at. Any pack contributes the same way, ours or yours, and every contribution passes the same review before Thinky or the OpenX MCP Server sees it.
What a kind can tell Thinky
A kind's capability manager tells Thinky about the kind through one optional hook,
getAziContribution (the code still carries the assistant's old name). A kind without the hook adds
nothing, and nothing about it changes. The hook returns:
| Field | What it is |
|---|---|
Kind | The manager's own Type. Every tool the kind contributes starts with it. |
Guide | What the kind is, in 3 to 6 sentences. Thinky reads it only while a panel of the kind is open. |
Tools | The kind's tools, described below. |
Status | Whether a node of the kind can run its tools now: ready, needs-sign-in or unavailable. |
Intents | Rare. Asks the kind adds to the step that decides what kind of turn a message is. |
The guide says what the kind is, never how Thinky should work. How Thinky works is the posture prompt every turn starts from, the same prompt the OpenX MCP Server serves to any AI. The kind's long reference stays in its own profile, which Thinky fetches by tool when it needs it.
The platform stamps the contribution with a Version: a hash of every text it declares. A changed
guide or description is a new version, and so is a changed context item.
Each tool declares:
| Field | What it is |
|---|---|
Name | Its name, by the rule below. |
Title | What a person reads in "Used:" and in confirmations. |
ModelDescription | What the model reads: what the tool does, when to use it, when not to, and what it returns. |
InputSchema | Its input. Property names say what they hold (warmQueryLookup, never id). |
OutputSchema | Optional. Its output: concise by default, paged, with stable ids. |
Effect | read or propose. Checked against the platform's review list, below. |
Load | When a turn loads it: open-panel, selected or search. |
Naming a tool
Every tool is named <kind>_<verb>_<noun>: lower case, the kind first, then a verb and a noun, for
example warmquery_read_query. A name is unique across every kind, and at most 64 characters long,
the longest name a model's tool list takes.
Write ModelDescription in at least three sentences: what the tool does, when to use it, when not
to, and what it returns. A description names only its own kind's tools. Naming another kind is fine;
naming another kind's tool is refused, so one kind never steers the model away from another's.
The two effects
| Effect | What it does |
|---|---|
read | Reads, and changes nothing. |
propose | Hands the person a change (a proposal, or a draft they keep and save) that they accept. |
There is no third effect: no contributed tool changes a workspace by itself. A person accepts every change.
The effect is never taken from the tool's own declaration. The platform keeps a review list that gives each tool its effect by name. A tool that is not on the list is refused until the platform reviews it, and a tool that declares a different effect from the list is refused.
The review list today:
| Tool | Effect |
|---|---|
warmquery_read_query | read |
warmquery_draft_query | propose |
warmquery_summarize_results | read |
interface_read_page | read |
interface_draft_query | propose |
database_read_containers | read |
database_propose_container | propose |
What Thinky is pointed at
At the start of each turn Thinky is told which panels are open: each one's title and kind, which one has focus, and which are behind a tab or pinned. A panel closed before the message is not mentioned. What a panel or a canvas points Thinky at is a context item, declared by its kind:
- A kind declares its items through a second optional hook,
DescribeThinkyContext. Each item kind has aNameunique in the kind, aLabel, what it points at (node,canvasorcollection), when it turns on by itself (panel-open,selected,canvas-in-focus,mentioned, orofferedfor only when the person turns it on), itsDefault, aHoverin plain words (what it does when it is on and what turning it off changes), and whether it brings the kind's guide (BringsGuide). ItsResolvenames the items offered now, from the workspace and what is on screen. A pack may declare canvas items too, as OpenX does for the workspace canvas. A kind without the hook offers no item. - An item never narrows what Thinky gets: every turn carries the whole workspace the person may
read. An item that is on names itself on the turn (its label, its target and what is selected on
it) and, with
BringsGuide, adds its kind's guide. It brings no tools: a kind's tools load whenever the workspace holds that kind (see below). - Set-up panels share nothing: API Keys, Billing, Team Members and Access Management declare no item, and neither do Live Stream, Proposals, the Inspector or Thinky itself.
- A secret field is never sent. The review refuses an item that points at one of its kind's secret fields.
- Items are identifiers only, never a record: at most 64 items in a turn, each identifier one line
of at most 120 characters, each label at most 480 characters, and at most 8 selected nodes
folded into one item. A
Resolvethat offers an item its kind did not declare, an item of another kind, or one that breaks a limit offers nothing for that turn.
The person sees the active items on the glance line above Thinky's box and can turn one off with a press; see What Thinky can see.
Thinky fetches the details behind an identifier by tool, when the ask needs them. When a kind's tool cannot run (the node needs a sign-in, or is unavailable), Thinky says why instead of acting as if the tool were missing.
What the review refuses
The registration review reads every kind's contribution and refuses it, naming the kind, the tool and the reason, when:
- it contributes under a kind other than its manager's
Type; - a tool name breaks the naming rule, or is longer than 64 characters;
- a tool name is already contributed by another kind (both are named);
- a guide or a description names another kind's tools;
- a description does not say what the tool does, when to use it, when not to, and what it returns;
- a tool is not on the review list, or declares a different effect from it;
- the guide is shorter than 3 or longer than 6 sentences, or gives working rules ("always...", "you should...") instead of saying what the kind is;
- a context item points at one of the kind's secret fields, has an empty
Hover, or repeats aNamein the kind.
A refused contribution is left out whole, with every reason. One kind's refusal, even a hook that throws, never stops the other kinds from contributing.
How many tools a turn loads
Models choose worse as their tool list grows, so a turn loads only a few tools:
- A core on every turn: the platform's own tools Thinky has always had (eight today), plus
search_tools. The core is trimmed only once the evals show a smaller one does as well. - The tools of each kind the workspace holds (at least one record the person may read), whatever is open or turned on in Thinky's context: at most 5 per kind. A kind the workspace does not hold loads none. A kind loads all of its tools or none of them. When room runs out, the focused panel's kind comes first, then the kinds in view, then those behind a tab, then the kinds with no panel open.
- A turn binds never more than 20 tools before a search.
- Every other tool is found with
search_tools, by its name or by the words of its description. What a search finds stays loaded for the rest of the turn.
While the workspace holds the same kinds and the same panels stay open, the list stays the same from turn to turn.
Where a contributed tool runs
The OpenX MCP Server is the one place a contributed tool runs. It lists each
reviewed tool under the same name, title, description and schemas the kind declares, with its effect
as the tool's annotations: a read tool is read-only, and a propose tool is not read-only and
never destructive. Each listing also names the tool's kind, effect and load in its _meta
(openx/azi-kind, openx/azi-effect, openx/azi-load), which is how Thinky knows which open panel
a tool belongs to.
Thinky calls a contributed tool through the server, so any AI connected to the server reaches the
same tool with the same rights. The server checks the caller's access rights on every call. A tool
is listed only once the platform runs it, so the server never lists a tool it cannot run. A
contributed tool needs the same right as the screen or route it matches. Today neither
warmquery_read_query nor database_read_containers needs one at the tool, because the Warm Query
and Database windows ask none of a person; anyone who can open the workspace can read what each
returns, like the windows (see
Errors and limits). The
server's tools, the contributed ones by their kind, are listed in Tools.
Evals before a contribution ships
A contribution ships with asks that must pick its tools and asks that must not. One shared set runs
every kind's asks with several panels open, so one kind's tools never confuse another's. Thinky must
match or beat each assistant it replaces on that assistant's own cases, set by set, and on time to
first word and cost per turn. A changed contribution (a new Version) is evaluated again; a version
that has already passed is not.
Related
On fathym.com: OpenX →