unfour

Overview Schema Source Related Servers Discussions Admin

Send API Request

unfour.api.send_request

Send saved or ad-hoc API requests through Unfour to reproduce failures during agent troubleshooting, with environment-aware execution and sensitive data masking.

Instructions

Sends either a saved API request by requestId or one ad-hoc request described by method/url/headers/query/body through the Unfour command bus. Use it to reproduce API failures during agent troubleshooting. Dev allows all HTTP methods; test allows sends but marks mutating methods as write risk; prod only allows GET/HEAD/OPTIONS. Non-2xx HTTP responses return structured status/body data rather than MCP tool failure. Sensitive headers, cookies, URL tokens, and JSON body fields are masked.

Input Schema

Name	Required	Description
`url`	No	URL for ad-hoc sends.
`body`	No	Optional request body for ad-hoc sends.
`name`	No	Optional display name for ad-hoc request history.
`query`	No	Optional query parameters as an object or array of {key,value,enabled}.
`method`	No	HTTP method for ad-hoc sends, such as GET, POST, PUT, PATCH, DELETE.
`headers`	No	Optional headers as an object or array of {key,value,enabled}. Sensitive values are redacted in results.
`bodyKind`	No	Optional body kind for ad-hoc sends (json, text, form, xml). Defaults to json.
`requestId`	No	Optional saved API request ID to replay. Omit when sending method/url directly.
`timeoutMs`	No	Optional timeout in milliseconds. Omitted or null defaults to 60000ms. 0 disables the HTTP timeout; positive values are passed through to the HTTP layer. All MCP calls remain subject to the independent 120-second MCP safety deadline.
`workspaceId`	No	Optional workspace ID for ad-hoc requests. Uses the active workspace if omitted.
`environmentId`	No	Optional per-call environment override. It is used for variable resolution and saved request scripts without changing the workspace active environment.

Output Schema

Name	Required	Description	Default
`ok`	Yes
`error`	No
`source`	Yes
`status`	No
`headers`	No
`bodyType`	No
`warnings`	No
`sizeBytes`	No
`truncated`	No
`durationMs`	No
`statusText`	No
`bodyPreview`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.12.0Oct 24, 2026
- addedOutput schema / properties / warnings
```
Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
```

Changed1 schema field changedv0.9.6Sep 15, 2026

changedInput schema / properties / timeoutMs / description

Previous value: -"Optional timeout in milliseconds. Omitted or null defaults to 60000ms; 0 means unlimited; positive values are used exactly."New value: +"Optional timeout in milliseconds. Omitted or null defaults to 60000ms. 0 disables the HTTP timeout; positive values are passed through to the HTTP layer. All MCP calls remain subject to the independent 120-second MCP safety deadline."

Changed3 schema fields changedv0.9.3Sep 4, 2026

changedInput schema / properties / timeoutMs / description

Previous value: -"Optional timeout in milliseconds. Maximum 60000ms (60 seconds)."New value: +"Optional timeout in milliseconds. Omitted or null defaults to 60000ms; 0 means unlimited; positive values are used exactly."

addedInput schema / properties / timeoutMs / minimum
```
Added value: +0
```

changedInput schema / properties / timeoutMs / type

Previous value: -"number"New value: +[
+  "integer",
+  "null"
+]

Changed1 schema field changedv0.9.1Sep 2, 2026

changedInput schema / properties / environmentId / description

Previous value: -"Optional environment ID (currently uses the workspace default environment)."New value: +"Optional per-call environment override. It is used for variable resolution and saved request scripts without changing the workspace active environment."

First observedv0.1.0Aug 20, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Goes well beyond the annotations: it discloses that non-2xx responses return structured status/body data instead of a tool failure, that responses mask sensitive headers/cookies/URL tokens/body fields, and that prod restricts methods. These are exactly the behavioral traits an agent needs before invoking an open-world, non-read-only send.

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

Conciseness4/5

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

Front-loads the two send modes in the first sentence, then stacks usage, environment rules, error semantics, and masking with no filler. Dense but purposeful; every sentence carries distinct information.

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

Completeness4/5

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

For an 11-parameter open-world tool with an output schema, the description covers purpose, environment constraints, error behavior, and masking, which is most of what an agent needs. Remaining details like timeout and workspace/environment overrides are handled in the schema, so completeness is high but not exhaustive.

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; the description adds value by explaining the either/or relationship between requestId replay and method/url ad-hoc sends, which the flat schema does not convey. It stops short of explaining timeoutMs, workspaceId, or environmentId nuances, but the schema already documents those.

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?

States a specific verb (sends) and resource, and disambiguates the two invocation modes: replay by requestId vs ad-hoc by method/url/headers/query/body. This is clearly distinguishable from sibling read tools like unfour.api.get_request and unfour.api.list_requests.

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

Usage Guidelines4/5

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

Names a concrete use case ('reproduce API failures during agent troubleshooting') and lays out environment gating: dev allows all methods, test flags mutating methods as write risk, prod restricts to GET/HEAD/OPTIONS. That is strong when-to-use context, though it does not name a competing sibling tool as an explicit alternative.

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

Deploy Server