Paperform

Test action

test_action

Destructive

Run one action of a connected app for real with the given input, on its own, outside any workflow: records are written, messages sent, and credits spent. A read-only action (find, get or list rows or records, search) is how to look at the person's data in that app, e.g. to check what a form or workflow just wrote to a sheet, instead of asking the person to look. Use it also to check a step works before publishing. Confirm with the user before calling this.

Returns Stepper's result as it came back: { status: "success" | "error" | "async", data, error, descriptions? }. An async action also carries asyncId, and result once it finished. Every call runs the action again, even with identical input. Pass workflow and node (the step's #id) to store a successful output on that step of the draft as its example, as the editor's "Run test action" does: the step must run this app, action and connection; it is checked before anything runs. The answer then carries example: { stored, note, workflow_version?, checks? } (checks: warnings on paths other steps read from this step that the stored output does not offer), and the draft's version changes, so fetch #source again (or pass workflow_version as edit_source's expected) before the next edit. A step that a later step or rule reads needs an example before the workflow can be published over MCP, and its paths can only be checked against one; edit_source and create store the app's own example for an action that has one, so test_action is only needed for the others. status "timeout" means Stepper did not answer in time and the action may still be running: the answer carries a retry_key; call again with the same input and that retry_key to get the attempt's outcome instead of running it twice (marked replayed: true), or status "in_progress" while it still runs. Read the timeout's message for how long the key holds, and never retry without it. error "dispatcher_error" means Stepper failed after the action may have run: it carries a retry_key the same way.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "app": "<app>",
      "action": "<action>",
      "connection": "<connection>",
      "input": "<input>"
    },
    "name": "test_action"
  }
}

Input Schema

Name	Required	Description
`app`	Yes	The app id, exactly as list({ type: "app" }) returned it.
`node`	No	With workflow: the #id of the trigger or step in the workflow's draft the example is for.
`input`	Yes	The parameter values chosen so far, key → value (plain values, not the source forms). Later parameters often depend on earlier ones.
`action`	Yes	An action key, from fetch on the app.
`workflow`	No	Optional: a workflow id, as list or fetch returned it, to store the output on one of its steps as that step's example. Needs node too, and write access to the workflow.
`retry_key`	No	Only to retry after status "timeout", status "in_progress" or error "dispatcher_error": the retry_key that answer returned. Omit it to run the action.
`connection`	Yes	A connection id for this app, from list({ type: "connection" }) or fetch on the app.

Output Schema

Name	Required	Description	Default
`data`	No
`error`	No
`result`	No
`status`	No
`asyncId`	No
`example`	No
`descriptions`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 6, 2026

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description reinforces these with concrete consequences: records are written, messages sent, credits spent, and every call re-runs even with identical input. It goes further than the annotations by documenting the timeout/in_progress/dispatcher_error retry_key protocol and the side effect of bumping the draft version after storing an example. The only shortfall is that the return-shape paragraph partly duplicates the output schema, so the net value added over structured data sits at a solid 3 rather than higher.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The content is front-loaded and almost every clause carries information, but it is delivered as three very long run-on paragraphs mixing the core call, example-storing, version invalidation and retry semantics. Some material (the full return shape, the retry explanation restated at the end) could be tightened or split, making it harder to scan than its value warrants.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter, high-blast-radius tool this covers everything an agent needs: required connection/app/action sourcing, the workflow+node example flow, the checks warnings, the draft-version invalidation and the retry protocol. The output schema exists, so the description's return-shape summary is a bonus rather than a gap-filler.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: node is tied to the step's #id and must be paired with workflow, the pairing is validated before anything runs, and retry_key must never be used except to replay a timeout, in_progress or dispatcher_error answer. It also clarifies that input values are plain values rather than source forms, which the schema does not state.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource ('Run one action of a connected app') with the crucial scoping clause 'on its own, outside any workflow', which separates it from run_workflow and from the editor's own test runner. It further splits read-only actions (find/get/list/search) from mutating ones, so an agent can classify the call before opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives multiple explicit when-to-use cases: to inspect a person's data via a read-only action (instead of asking them to look), to verify a step before publishing, and to seed an example on a step. It also gives an explicit when-not: edit_source and create already store the app's own example, so test_action is only needed for actions without one. It adds a procedural gate, 'Confirm with the user before calling this.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Paperform tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?