screens_list — find screen workflows
Use this when the requested workflow is unknown. It searches local screen-source inventory and returns the implemented workflow descriptions. It does not list the authenticated account's channels; that is channels_list. If you already know the correct tool and its input rules, discovery need not be repeated.
Input
| Field | Type | Required | Default and limits |
|---|---|---|---|
query |
string | No | Empty string; case-insensitive substring match over source path and title. |
offset |
integer | No | 0; nonnegative, at most 9,007,199,254,740,991. |
limit |
integer | No | 20; from 1 through 50. |
null is not a substitute for an omitted field.
{"query":"account","offset":0,"limit":20}
Inputs
| Field | Required here | Contract |
|---|---|---|
query |
No | string; default `` |
offset |
No | integer; minimum 0; default 0 |
limit |
No | integer; minimum 1; maximum 50; default 20 |
Result
The application payload is returned in both structuredContent and JSON text as described in common results. This discovery payload does not use top-level application status or code fields.
| Field | Meaning |
|---|---|
kind |
screen-source-candidates. |
total |
Number of source candidates matching the query. This is not a tool or completed-screen count. |
offset |
Requested offset. |
nextOffset |
The next offset, or null when there is no later matching page. |
items |
Current page of inventory entries, including path, title, status, workflows, and kind. |
note |
Clarifies source inventory versus executable workflows. |
Keep the same query and limit when following nextOffset. An empty or out-of-range page can still contain implementedWorkflows. Source inventory-only entries are not executable. Take a workflow's id from implementedWorkflows and pass it to screen_describe; do not use a source file path as a screen ID.
Effects, errors, and limits
In stdio this reads docs/audit/screen-workflows.json and local catalog definitions. It requires no publ authentication and makes no publ API request. It does not change channels, credentials, or jobs. Invalid pagination is rejected by MCP input validation. Missing or unreadable inventory may produce a server/tool error rather than an application error with a guaranteed code.
The catalog is static implementation metadata. It does not prove live permissions or plan availability. Confirm a tool in that endpoint's actual discovery result before calling it.
Hosted resource scope
The hosted implementation filters executable guidance for the authorized resource while retaining the global source inventory and its query/pagination. Additional fields are:
| Field | Meaning |
|---|---|
resourceScope |
Bound account or selected-channel resource; a channel resource includes its exact channelCode. |
globalWorkflowCount |
24 in this revision; reference inventory, not available access. |
implementedWorkflows |
Only workflow descriptions with at least one business tool in this resource. Mixed workflows contain a reduced contract. |
items[].globalWorkflowIds |
Original global associations for that source item, retained only as inventory. |
items[].workflows |
Associations that have available business tools in this resource. |
items[].availability |
available when scoped workflows remain, outside-authorized-scope when only global associations exist, or not-implemented when the item has no workflow. |
items[].status |
Set to outside-authorized-scope for excluded global associations; otherwise retains the inventory status. |
The local scope policy admits 20 tools/six usable workflows for an account and 48 tools/20 usable workflows for a selected channel. These sets overlap. A source item's available label does not mean that its whole original screen is implemented; inspect each workflow's availability and tools using screen_describe.
For example, account.channels has account directory/archiving tools in an account resource, but only the channel context read in a selected-channel resource. The global source title does not override the scoped tool list. Shared status/resume tools also restrict recovery to task types admitted by that resource. Out-of-scope tools cannot be invoked through this connection simply by knowing their names.
These are implemented and locally verified filtering rules.
Implementation: src/catalog.ts::screenAreas, registration in src/server.ts, and src/hosted/scope.ts.
Orders and refunds catalog extension
Their operations are orders_get and refunds_get. the workflow guide supplies constraints and known core-response limits. Recovery remains 34 types.