unfour

Overview Schema Source Related Servers Discussions Admin

Send API Request

unfour.api.send_request

Send a saved API request by requestId or create an ad-hoc request with method, URL, headers, query, and body. Reproduce API failures during troubleshooting; non-2xx responses return structured status and body data.

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

TableJSON 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

TableJSON Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

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.9/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, but the description adds substantial behavioral context: environment-dependent method restrictions, non-2xx response behavior, masking of sensitive headers/cookies/URL tokens/JSON body fields, and the distinction between HTTP timeout and the MCP safety deadline. This goes well beyond what annotations provide.

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

Conciseness5/5

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

The description is compact and front-loaded: the core action and two modes appear in the first sentence, followed by the use case, environment restrictions, response behavior, and masking. Every sentence adds information; there is no filler or repetition of schema content.

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 tool with 11 parameters, no required parameters, and an output schema, the description covers the essential decision points: which mode to use, environment restrictions, response handling, and security masking. The output schema handles return values, so the description doesn't need to. The only minor gap is that it doesn't explicitly say what happens if both requestId and method/url are provided, but the schema's 'Omit when sending method/url directly' covers that.

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 description coverage is 100%, so the schema already documents all 11 parameters. The description adds value by explaining the two mutually exclusive modes (requestId vs method/url), the environment-dependent method restrictions, and the timeout semantics (0 disables HTTP timeout, 120s MCP deadline). It doesn't detail every parameter, but the schema already does that, and the description clarifies the key relationships.

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 description states a specific verb ('sends') and resource ('API request through the Unfour command bus'), and distinguishes two modes: replaying a saved request by requestId or sending an ad-hoc request by method/url/headers/query/body. It also names a concrete use case ('reproduce API failures during agent troubleshooting'), which clearly separates it from sibling tools like list_requests or get_request.

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?

The description explicitly explains when to use the tool ('reproduce API failures during agent troubleshooting') and gives environment-specific guidance: dev allows all methods, test marks mutating methods as write risk, prod only allows GET/HEAD/OPTIONS. It also clarifies that non-2xx responses return structured data rather than MCP tool failure, which tells the agent how to interpret results. This is strong usage guidance.

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

Deploy Server